Here is the awkward part: nothing was broken. No alert fired, no error rate moved, no dashboard turned red. Third-party API spend is one of the few production signals with no failure mode attached to it. A background job that polls a vendor every thirty seconds and gets back the exact same payload it got last time looks, from the outside, identical to a healthy integration. It just costs money every single time.

This post is about how to reduce SaaS API costs by changing the shape of your calls rather than by renegotiating your contract. Six levers, in the order I’d pull them: read the billing unit, kill pointless polling, collapse N+1 patterns, cache honestly, stop your own retry amplification, and attribute spend so you can tell whether any of it worked.

Start with the billing unit, not the call count

The single most common mistake I see is optimising HTTP requests when the vendor doesn’t bill HTTP requests. Before you touch any code, read the pricing page carefully enough to answer one question: what is the countable thing?

It varies more than people expect:

• Per request. The obvious one. Geocoding, enrichment, most REST endpoints.
• Per session. Google Maps Platform bills Places Autocomplete this way when you pass a session token: the whole keystroke stream plus the terminating Place Details call is grouped and billed as one unit. Omit the token, or reuse one across sessions, and every keystroke request is billed individually.
• Per token issued. Auth0’s machine-to-machine quotas count access tokens obtained through the client credentials flow, not the API calls you make with them. A service that fetches a fresh token on every outbound request is burning the meter for no reason.
• Per input and output token. LLM providers. Output is typically priced higher than input, which makes “be concise” a cost control and not just a style note.
• Per record, event, or message. Twilio, SendGrid, most streaming and messaging platforms. One API call can carry many billable units.
• Not at all. Stripe doesn’t bill you per API call; the constraint there is a rate limit, not a line item. Optimising those calls buys you reliability headroom, not money.

Getting this wrong sends you down the wrong path for weeks. Batching requests against an endpoint that bills per record changes your request count and leaves the invoice exactly where it was. Read the unit first.

Lever one: stop polling for things that rarely change

This is almost always the biggest single line, and it’s invisible because it’s steady. A sync job on a five-minute cron is 288 calls a day per resource. Multiply by resources, by environments, by the replicas you quietly scaled to three, and you get a number with no relationship at all to how often the data changed.

Conditional requests, when the vendor honours them

If the API returns an ETag or Last-Modified header, store it and send it back on the next poll as If-None-Match or If-Modified-Since. If nothing changed you get a 304 Not Modified with an empty body.

# First call: capture the ETag from the response headers
curl -sS -D - -o /dev/null 
  -H "Authorization: Bearer $TOKEN" 
  https://api.github.com/repos/OWNER/REPO/pulls

# Second call: send it back and check the status code only
curl -sS -o /dev/null -w '%{http_code}n' 
  -H "Authorization: Bearer $TOKEN" 
  -H 'If-None-Match: "PASTE_THE_ETAG_HERE"' 
  https://api.github.com/repos/OWNER/REPO/pulls

-D - dumps response headers to stdout so you can see the etag value. -w '%{http_code}' on the second call prints just the status, which is all you care about: 304 means the resource is unchanged and you saved a payload.

Whether that saves money depends on the vendor. GitHub documents that a conditional request returning 304 doesn’t count against your primary rate limit when it’s correctly authorised. Plenty of other vendors return 304 happily and bill it anyway. Test against your own invoice before you assume.

Three things that bite people with ETags:

• They’re per-page on paginated endpoints. A 304 on page one says nothing about pages two through five, so store one ETag per page.
• They can be scoped to the credential. Rotate a token and your stored ETags may stop matching, which quietly turns your conditional requests back into full ones.
• GraphQL endpoints generally don’t do conditional requests at all. You cache those yourself, keyed on a hash of the query and its variables.

Webhooks, when they exist

The proper fix is to stop asking. If the vendor supports webhooks, the call count collapses from “one per interval” to “one per actual change”, which is usually a difference of two orders of magnitude on a slow-moving resource.

Be honest about what it costs, though. Webhooks need a publicly reachable endpoint, signature verification, idempotent handling because vendors redeliver, a dead-letter path, and a reconciliation sweep for deliveries that never arrived. On a resource that changes every few seconds, polling is simpler and the savings are small. On one that changes twice a week, the webhook pays for itself immediately.

A middle option people forget: many APIs expose a cheap “has anything changed” endpoint, a sync cursor, or a delta token. Poll that on a tight interval and only fetch the expensive payload when it moves.

Lever two: collapse the N+1 pattern

You know this one from databases, and it shows up identically against third-party APIs. Fetch a list of 200 items, then fetch each item’s detail individually: that’s 201 billable calls where the vendor probably offers a way to do it in one or two. Look for:

• Expansion or embed parameters. Many REST APIs let you inline related objects in the list response so the detail calls disappear entirely.
• Field selection. Asking for fewer fields is free on per-request billing but matters a lot where the field tier drives the price. Google Places is explicit about this: requesting a single higher-tier field upgrades the whole response to that tier’s pricing.
• Bulk and batch endpoints. Salesforce, Algolia, most CRMs and search platforms have one. They’re usually documented in a corner nobody reads.
• Larger pages. If the endpoint accepts a page size of 200 and you’re defaulting to 25, you’re paying eight times as many calls to fetch identical data.

The page-size one is the cheapest win in this entire post and it’s a one-line change. Check your client library defaults today.

Lever three: cache with a boring, honest TTL

Caching third-party responses is the lever everyone reaches for first and gets subtly wrong. Three failure modes matter more than the cache itself.

Stampede. A popular key expires, fifty concurrent requests all miss, and fifty identical calls go out to the vendor. You just paid fifty times for one refresh, at the worst possible moment.

No negative caching. A lookup that returns “not found” is usually not cached at all, so the same failing lookup hammers the vendor forever. Cache your 404s. Short TTL, but cache them.

Cache key design. If your key doesn’t include the credential or tenant, you will eventually serve one customer’s data to another. This is the one mistake in this post that turns a cost problem into an incident.

You don’t necessarily need application code for this. An Nginx instance in front of the vendor handles all three, and it’s the approach I reach for first when several services hit the same API:

proxy_cache_path /var/cache/nginx/api levels=1:2 keys_zone=api_cache:20m
                 max_size=1g inactive=60m use_temp_path=off;

server {
    listen 127.0.0.1:8080;

    location / {
        proxy_pass https://api.vendor.example;
        proxy_set_header Host api.vendor.example;

        proxy_cache api_cache;
        proxy_cache_key "$request_method$request_uri$http_authorization";

        proxy_cache_valid 200 5m;
        proxy_cache_valid 404 30s;

        proxy_cache_lock on;
        proxy_cache_use_stale updating error timeout;
        proxy_cache_background_update on;

        add_header X-Cache-Status $upstream_cache_status;
    }
}

Reading that from the top down, because every directive is there for a reason:

• proxy_cache_key includes $http_authorization, so responses are isolated per credential. That’s the tenant-leak fix.
• proxy_cache_valid 404 30s is the negative caching. Failed lookups stop being free traffic for the vendor.
• proxy_cache_lock on is the stampede fix. Only the first request for a given key goes upstream; the rest wait for it.
• proxy_cache_use_stale updating plus proxy_cache_background_update on serves the stale copy while a single background request refreshes it. Latency stays flat and you don’t pay a thundering herd at every expiry.
• X-Cache-Status gives you HIT, MISS, STALE or UPDATING in the response so you can actually measure your hit rate instead of guessing at it.

The trade-off is worth stating plainly: you’re now serving data that can be five minutes stale, and you own another moving part. Fine for a currency rate or a product catalogue. Not fine for an inventory count on a checkout page. Set the TTL from how wrong the data is allowed to be, never from how much you want to save.

Where the caller is distributed, Redis with a short lock key does the same job in application code, and a small always-on VPS from something like InterServer or DigitalOcean is plenty to host either the proxy or the cache. At the edge, Cloudflare Workers with KV lets you cache vendor responses close to users, which helps when the calls originate from browsers rather than your backend.

Lever four: stop paying for your own retries

This produces the sudden spike rather than the slow creep, and people miss it because retries feel like resilience.

The vendor wobbles. Every client retries. With a fixed delay they retry in lockstep, so the vendor gets a synchronised wave on top of normal load, struggles longer, and generates more retries. AWS’s architecture write-up on exponential backoff and jitter is the canonical reference, and its central finding is worth repeating: backoff alone still leaves visible clusters of calls. Randomising each client’s delay is what decorrelates the herd, and in their simulation it cut total call count substantially.

import random, time

BASE = 0.5      # seconds
CAP  = 30.0     # never sleep longer than this

def sleep_before_retry(attempt):
    # capped exponential backoff, then full jitter
    window = min(CAP, BASE * (2 ** attempt))
    time.sleep(random.uniform(0, window))

The cap stops a long outage turning into hour-long sleeps. The random.uniform(0, window) is the jitter: two processes that failed at the same instant now wake at different times. Note that full jitter can occasionally produce a near-zero delay, which is fine for transient errors but too aggressive for throttling responses that reset on a per-minute window. For a 429, honour the Retry-After header if the vendor sends one, and use a jitter formula with a guaranteed floor if they don’t.

Three more rules that cost nothing to implement:

1. Never retry a 4xx except 429. A 400 or a 422 will fail identically forever. Every one of those retries is a billed call buying you nothing.
2. Cap retries as a fraction of traffic. A retry budget (say, retries may not exceed some small percentage of total requests) is the only control that sees the system-wide picture. Per-client backoff can’t.
3. Check your layers. If the SDK retries three times, your HTTP client retries three times, and your job runner retries three times, one logical operation is up to twenty-seven calls. This stacking is extremely common and almost never intentional.

For writes, retrying safely needs an idempotency key so the vendor deduplicates rather than creating two of whatever you asked for. Stripe’s Idempotency-Key header is the pattern most others copied. Without it, teams disable retries on writes entirely and then eat manual reconciliation work instead.

Lever five: move latency-tolerant work off the synchronous path

Ask a blunt question about each integration: does a human wait on this response?

Nightly enrichment, classification, report generation, bulk address validation, embedding backfills. Nobody is waiting. Several vendors, including the major LLM providers, offer asynchronous batch endpoints at a discount to the synchronous rate in exchange for a looser delivery window. Rates move, so check current terms rather than a number you read somewhere, but the mechanism is stable and the discount is usually substantial.

Even without a batch endpoint, moving work behind a queue lets you coalesce. Ten events touching the same customer record within a minute become one enrichment call instead of ten. That deduplication window is often worth more than the batch discount.

Lever six: attribute the spend or you’re guessing

Everything above is unfalsifiable until you can answer: which feature, which tenant, which job. The invoice gives you the total and never the cause. What I’d put in place, in order:

1. Route outbound calls through one place. A shared HTTP client wrapper or the caching proxy above. If every service instantiates its own client, you have no chokepoint and no measurement.
2. Emit a counter per call with labels for vendor, endpoint, status class, and cache result. Keep the label set small; per-tenant labels will blow up your metrics cardinality and trade one bill for another.
3. Build one unit-cost metric. Vendor spend per active tenant per month. It’s the only number that survives growth, because raw spend going up during a good quarter is not a problem.
4. Alert on call rate, not on the bill. A rate alert fires in minutes. An invoice fires in thirty days. Grafana, Prometheus, Datadog, CloudWatch, whatever you already run is fine; the point is that the alert exists at all.
5. Track cache hit rate as a first-class SLI. When someone changes a cache key format and the hit rate silently drops to zero, this is the graph that tells you before the invoice does.

Troubleshooting: the bill jumped and nothing shipped

Work down this list. In my experience the cause is usually in the first four.

• Replica count changed. Autoscaling or a Kubernetes replica bump multiplies every cron-driven poller. Check whether your scheduled jobs have leader election, or whether all five pods are dutifully polling the same endpoint.
• Cache hit rate collapsed. A changed key format, a Redis eviction policy under memory pressure, or a TTL someone dropped “temporarily” during debugging. Graph the hit rate over the period, not the current value.
• Retry loop against a persistent 4xx. Look for a flat, high rate of identical failing calls. This has the distinctive signature of high call volume with zero successful responses.
• A non-production environment pointed at production credentials. Staging, a CI pipeline, or an integration test suite running on every commit. Check whether calls are arriving from IPs you don’t recognise.
• Session or token handling regressed. A refactor that dropped a session token parameter, or a service that stopped caching its auth token and now mints a new one per request.
• Legitimate growth in an expensive segment. A few large customers using a costly feature move the bill without moving call count much. Not a bug, but worth ruling in before you go hunting for one.

If the vendor exposes per-key usage breakdowns in their dashboard, split your credentials by service before your next incident. Separate API keys per environment and per major consumer turn a whodunnit into a two-minute lookup.

Common mistakes

• Optimising the endpoint that’s easy to change rather than the one that dominates the bill. Rank by spend first.
• Caching without a per-credential key, and finding out the hard way in a multi-tenant system.
• Treating 304 responses as free when your specific vendor bills them anyway.
• Setting TTLs from a savings target rather than a staleness tolerance, and finding out during a customer escalation.
• Leaving retry logic enabled at three separate layers and calling the result “defence in depth”.
• Adding per-tenant labels to outbound-call metrics and moving the cost from the API vendor to the observability vendor.
• Shipping the optimisation and never checking the next invoice against the prediction.

Best practices worth keeping

• One outbound HTTP client wrapper per service, with timeouts, retries, and metrics configured in exactly one place.
• Separate API credentials per environment and per major consumer, so usage dashboards mean something.
• Cache auth tokens until shortly before expiry. Refresh early, not on every call.
• Add jitter to scheduled jobs as well as to retries. Everything set to run at the top of the hour arrives at the vendor as a spike.
• Write down the staleness tolerance for each cached resource next to its TTL, so the next person doesn’t have to reverse-engineer your reasoning.
• Re-check the pricing page after any vendor product update. Billing units change more often than endpoints do.

FAQ

How do I find out which service is driving my API spend?

Start with the vendor’s own usage dashboard broken down by API key. If all your services share one key, that’s the first thing to fix. Failing that, log every outbound call at the client wrapper with the endpoint and calling service, and aggregate for a week. A week of honest logs beats a month of theorising.

Do ETags actually reduce SaaS API costs, or just help with rate limits?

It depends entirely on the vendor. GitHub documents that an authorised conditional request returning 304 doesn’t count against the primary rate limit. Others count every request regardless of status. Run a controlled test: a known number of conditional calls over a billing period, then compare against the usage report. Don’t assume either way.

Is caching third-party API responses allowed?

Usually yes, but not always, and some terms of service restrict how long you may store certain data. Mapping and place data is a common example of restricted caching. Check the terms for the specific vendor before you build a permanent store, particularly if you’re caching anything personally identifiable.

How much can caching realistically cut an API bill?

Nobody can give you a number without knowing your traffic. Estimate it yourself: for a candidate endpoint, count distinct request keys versus total requests over a day. That ratio is roughly your ceiling for hit rate. Multiply by the endpoint’s share of spend. If the answer is a couple of percent, spend your time elsewhere.

Should I always replace polling with webhooks?

No. The comparison is change frequency against poll frequency. If the resource changes almost as often as you poll, you save little and take on signature verification, redelivery handling, and a reconciliation job. Webhooks win decisively on slow-changing resources and on anything where you’re polling more than a handful of objects.

Does rate limiting my own users reduce vendor costs?

Only when user actions map directly to vendor calls, such as a search box that fires an upstream request per keystroke. Debouncing input and enforcing per-plan quotas helps a lot there. For background processing driven by your own schedules, user rate limits change nothing.

Should I disable retries to save money?

No. Fix them instead. Capped exponential backoff with jitter, no retries on non-429 client errors, a retry budget, and retry logic living at exactly one layer. Disabling retries entirely trades a cost problem for a reliability problem, and reliability problems are more expensive.

The one thing worth remembering

Most efforts to reduce SaaS API costs fail because they start with code. They should start with two questions: what is the vendor actually counting, and which of my calls returned information I already had?

Answer those honestly and the work usually collapses to a handful of unglamorous changes. Raise a page size. Cache a token. Put a lock around a cache refresh. Delete a poller that was watching something that changes twice a week. None of it is clever. All of it shows up on the next invoice, which is the only review that counts.

Need help getting your API spend under control?

This is work I take on regularly. Typical engagements look like:

• Auditing outbound API traffic to find which endpoints, jobs and tenants are driving the bill, and ranking them by spend rather than by how obvious they are.
• Building a caching layer in front of chatty vendor APIs, with Nginx, Redis or Cloudflare Workers, including stampede protection and per-tenant key isolation.
• Replacing polling jobs with webhook receivers or delta-token syncs, with signature verification, idempotent handling and a dead-letter path.
• Auditing timeout and retry configuration across services to remove stacked retries and add proper backoff, jitter and retry budgets.
• Moving latency-tolerant workloads onto batch or queue-based paths, with deduplication windows that cut call volume before it reaches the vendor.
• Setting up call-rate and cache-hit-rate dashboards and alerts in Prometheus, Grafana, Datadog or CloudWatch so the invoice is never the first signal.

If you’ve got a cost graph that’s climbing, a job you suspect is over-polling, or a client wrapper you’re not sure about, send it over and I’ll tell you what I’d look at first.

The post Optimizing API Calls to Reduce SaaS Costs: Six Levers That Actually Move the Bill appeared first on John Nessime.

That is the failure mode worth taking seriously. Not slowness, not downtime — the CDN cached a page that was personalised for one user and served it to everybody else. And you will not notice, because your browser holds a session and looks fine. The people seeing the broken version are the ones who never contact you.

Getting CDN setup right for a dynamic site is not about finding the right toggle in a dashboard. It is about deciding, per route, what is public and what is personal, and then making the origin say so clearly enough that no edge node has to guess.

Sort your routes before touching any config

Every URL on your site falls into one of three buckets. Write the list out — actually write it, this takes ten minutes and prevents the incident above.

• Static assets. CSS, JS, images, fonts. Identical for everyone, content-addressed if your build is sensible. Cache these hard, for a year.
• Public dynamic. Generated by the application but identical for every anonymous visitor. Blog posts, product pages, category listings. This is where the real performance win lives, and where most people leave everything uncached out of nervousness.
• Private dynamic. Anything personalised or authenticated. Carts, dashboards, checkout, admin, most API responses. Never cached at a shared cache, no exceptions.

The middle bucket is the whole game. If you cache only the first bucket you have built an asset CDN and left the expensive work untouched. If you accidentally cache the third, you have a data leak.

The header that separates the buckets

The single most useful thing to understand is the difference between private and no-store, because people use them interchangeably and they mean very different things.

# Static assets with a content hash in the filename
Cache-Control: public, max-age=31536000, immutable

# Public dynamic: edge caches it, browser revalidates
Cache-Control: public, s-maxage=300, max-age=0, must-revalidate

# Personalised: browser may cache, shared caches must not
Cache-Control: private, no-store

# Genuinely sensitive: nobody stores this anywhere
Cache-Control: no-store

private means “a browser cache may keep this, a shared cache may not”. no-store means “do not write this to disk anywhere”. For an authenticated dashboard you want both. For a bank statement you want no-store alone.

The other key pair is s-maxage versus max-age. s-maxage applies only to shared caches — the CDN — and overrides max-age there. That lets you cache a product page at the edge for five minutes while telling browsers to revalidate every time, so a price change propagates in five minutes rather than living in someone’s browser for an hour.

Set caching headers at the origin, per route, and let the CDN follow them. Configuring cache rules only in the CDN dashboard means the policy lives somewhere your application code cannot see and your staging environment does not have.

Vary, and how it quietly ruins your hit rate

Vary tells caches that the response depends on a request header, so a separate copy is stored per distinct value. Used precisely it is essential. Used carelessly it destroys your cache.

# Fine. A handful of encodings, a handful of variants.
Vary: Accept-Encoding

# Also fine if you genuinely serve different content per language
Vary: Accept-Encoding, Accept-Language

Now the one to avoid:

# Effectively disables caching. Every browser build is a distinct
# User-Agent string, so every visitor gets their own cache entry.
Vary: User-Agent

If you need device-specific responses, most CDNs expose a normalised device-type value with two or three possible values. Use that rather than the raw header.

Vary: Cookie deserves its own warning. It looks like a safe way to separate logged-in from anonymous traffic, and it is not — every visitor carries slightly different cookies from analytics and consent tools, so you get a near-unique cache key per person. The correct approach is to make the presence of a session cookie bypass the cache entirely, rather than varying on it.

Cookies are where sites actually break

Two rules, and between them they prevent most CDN incidents.

Rule one: a session cookie means bypass

If a request arrives carrying your session cookie, it should go to origin uncached. Most CDNs let you express this as a cache rule; in nginx, if you are running your own edge, it is a variable:

map $http_cookie $bypass_cache {
    default                 0;
    "~*wordpress_logged_in" 1;
    "~*woocommerce_items"   1;
    "~*comment_author"      1;
    "~*PHPSESSID"           1;
}

location / {
    proxy_cache            edge_cache;
    proxy_cache_bypass     $bypass_cache;   # do not serve from cache
    proxy_no_cache         $bypass_cache;   # do not write to cache
    proxy_cache_valid      200 301 302 5m;
    proxy_cache_use_stale  error timeout updating http_500 http_502 http_503 http_504;
    proxy_cache_lock       on;

    add_header X-Cache-Status $upstream_cache_status always;
    proxy_pass http://origin;
}

You need both directives. proxy_cache_bypass stops a logged-in user being served a cached anonymous page. proxy_no_cache stops their personalised response being written into the cache for everyone else. Setting only the first is a common and dangerous mistake — the read path is protected while the write path is wide open.

That X-Cache-Status header is not decoration. It is how you verify any of this actually works.

Rule two: strip cookies you do not need

Analytics and consent tools set cookies on every visitor. If your CDN treats any cookie as a bypass signal, your anonymous traffic stops being cacheable the moment you add a tag manager. Configure the CDN to ignore everything except the specific cookies that matter, and be explicit about which those are.

Query strings, and the cache-key explosion

By default many CDNs include the full query string in the cache key. Then a marketing campaign starts appending utm_source, utm_medium, fbclid and friends, and one page becomes thousands of cache entries that each miss exactly once.

Decide deliberately which parameters affect the response:

• Include parameters that change the content — ?page=2, ?sort=price, ?category=boots.
• Ignore tracking parameters entirely. They never change what the server renders.
• Normalise order where the CDN supports it, so ?a=1&b=2 and ?b=2&a=1 are one entry rather than two.

An allowlist is safer than a blocklist here. New tracking parameters appear constantly; the set of parameters your application actually reads changes rarely.

Keeping dynamic pages cached without going stale

The usual objection to caching public dynamic pages is that content changes. Two mechanisms solve this, and together they let you cache aggressively without serving stale content for long.

Stale-while-revalidate

Cache-Control: public, s-maxage=60, stale-while-revalidate=600, stale-if-error=86400

Read that as three separate promises. Fresh for sixty seconds. For the following ten minutes, serve the stale copy immediately while fetching a fresh one in the background — so nobody waits. And if the origin is throwing errors, keep serving the stale copy for a day rather than showing a 502.

That last directive turns your CDN into a partial outage shield. It is one of the highest-value headers on this page and it costs nothing.

Purge on change

Time-based expiry is a blunt instrument. If your application knows when a product price changed, tell the CDN immediately rather than waiting for a TTL.

Tag-based purging is the version worth building toward — tag responses by the entities they contain, then purge by tag when an entity changes:

# Origin response for a product page
Cache-Tag: product-1234, category-boots, layout-main

Update product 1234 and you purge one tag, invalidating the product page, every category listing it appears on, and the homepage if it is featured — without knowing any of those URLs in advance. Header name and support vary by provider, so check what yours calls it.

Verifying it before you point DNS

Test with curl, not a browser. Your browser has cookies, a warm local cache and an opinion; curl tells you the truth.

# What headers is the origin actually sending?
curl -sI https://example.com/products/boots | grep -i 'cache-control|vary|set-cookie'

# Twice in a row: second request should show a HIT
curl -sI https://example.com/products/boots | grep -i 'x-cache|age'
curl -sI https://example.com/products/boots | grep -i 'x-cache|age'

Now the test that matters most. Request an authenticated page with a real session cookie and confirm it never returns a cache hit:

curl -sI https://example.com/account 
  -H "Cookie: session=<a-real-session-value>" 
  | grep -i 'x-cache|cache-control'

You want BYPASS or MISS, and Cache-Control: private. If that ever shows HIT, stop and fix it before going further.

The leak test, which is the one people skip: fetch a personalised page with a session, then fetch the same URL with no cookies at all and confirm you get the anonymous version.

# With a session
curl -s https://example.com/account -H "Cookie: session=<value>" | grep -i 'welcome back'

# Immediately after, with nothing. Should NOT show the personalised content.
curl -s https://example.com/account | grep -i 'welcome back'

If the second command finds personalised content, the CDN cached a private response. That is the Monday-morning email, and you have just caught it before your customers did.

Test the edge before DNS points at it

curl -sI https://example.com/ --resolve example.com:443:<edge-ip>

That sends a real request to a specific edge node with the correct hostname and TLS SNI, without changing DNS. It is how you find out whether the whole thing works before any user does.

Things that break in ways nobody expects

Client IPs all become the CDN’s

Your logs fill with edge node addresses, rate limiting starts throttling everyone at once, and geolocation breaks. The real address arrives in a forwarded header, and your origin has to be configured to trust it — but only from the CDN’s address ranges. Trusting X-Forwarded-For from anywhere lets any visitor claim any IP they like, which turns a logging annoyance into an authentication bypass.

Redirect loops

The CDN talks to your origin over HTTP, the origin sees a non-HTTPS request and redirects to HTTPS, which comes back through the CDN, forever. Either terminate TLS at the origin too, or have the origin trust X-Forwarded-Proto when deciding whether to redirect.

POST responses getting cached

Shouldn’t happen by default, but a badly written cache rule can do it, and the result is one user’s form submission response served to the next person. Only cache GET and HEAD. Ever.

Websockets and streaming

Websocket upgrades and server-sent events need to pass through untouched. Buffering breaks streaming responses silently — the connection works, the data just arrives in one lump at the end, which looks like an application bug rather than a proxy setting.

Set-Cookie on a cacheable response

If a public page returns Set-Cookie and gets cached, every subsequent visitor receives that cookie — potentially somebody’s session identifier. Most CDNs refuse to cache responses carrying Set-Cookie, but not all, and not always. Check your origin is not setting cookies on pages you intend to cache.

Rolling it out without a bad week

1. Write down the route list. Three buckets, every path accounted for.
2. Set headers at the origin first, with the CDN not yet in front. Verify with curl.
3. Start with everything bypassed except static assets. A CDN that caches nothing still terminates TLS closer to users and is not a failure.
4. Add public dynamic routes one at a time, with short TTLs. Sixty seconds, then extend once you trust it.
5. Run the leak test after every rule change, not just at the end.
6. Watch origin request volume. It should drop noticeably. If it does not, something is bypassing that you think is caching.
7. Keep a purge command to hand and know how long a full purge takes before you need it.

Common mistakes

• Testing only in a logged-in browser, where cached-private-content bugs are invisible.
• Setting proxy_cache_bypass without proxy_no_cache, protecting reads but not writes.
• Vary: Cookie or Vary: User-Agent, which shatters the cache into near-unique entries.
• Leaving tracking parameters in the cache key.
• Configuring caching in the CDN dashboard only, so the policy is invisible to your code and absent from staging.
• Trusting forwarded IP headers from any source rather than only the CDN’s ranges.
• Using private where you needed no-store, or the reverse.
• Caching everything on day one and finding the problems in production.

Best practices

• Default to no caching, then allow specific routes. Opt-in beats opt-out when the failure mode is a data leak.
• Own the policy at the origin so it travels with your code and exists in staging.
• Use s-maxage for the edge and max-age for browsers. They are different problems.
• Always set stale-if-error. It is free outage insurance.
• Expose a cache status header and monitor hit ratio per route, not site-wide.
• Build purge-on-publish into the application rather than relying on TTLs alone.
• Make the leak test part of CI, so a future config change cannot reintroduce it quietly.

Frequently asked questions

Can a CDN cache dynamic pages at all?

Yes, and that is where most of the benefit is. Dynamic does not mean personalised. A blog post rendered from a database is identical for every anonymous visitor and can be cached at the edge for minutes. Only genuinely per-user content must bypass.

What is the difference between private and no-store?

private permits browser caching but forbids shared caches. no-store forbids writing the response to any cache at all. Use both for authenticated pages; use no-store alone for genuinely sensitive responses.

Why did my hit ratio collapse after adding a cookie banner?

Because the consent tool sets a cookie on every visitor and your CDN treats any cookie as a bypass signal, or you are varying on Cookie. Configure the CDN to ignore all cookies except the specific ones that indicate a session.

How do I verify private pages are not being cached?

Request the page with a real session cookie and confirm the cache status shows a bypass or miss, never a hit. Then request the same URL with no cookies and confirm the personalised content is absent. Do this after every cache rule change.

Should I cache API responses?

Public read-only endpoints, yes — with short TTLs and a cache key that includes whatever parameters affect the response. Anything requiring an Authorization header should be treated as private by default.

Do I still need caching at the origin?

Yes. The CDN protects you from repeat requests for the same URL; it does nothing for the first request, for uncacheable routes, or during a purge. Origin-level caching handles those.

Wrapping up

A CDN in front of a dynamic site is a classification problem wearing a performance costume. Sort your routes into public, private and static; express that at the origin with Cache-Control; make session cookies a hard bypass on both the read and write path; and keep tracking parameters out of the cache key.

Then test the way an anonymous visitor arrives, not the way you browse your own site. Two curl commands — one with a session, one without — catch the failure that matters, and they take about ten seconds. Run them every time you change a cache rule and the Monday email never arrives.

Want a CDN set up without the surprises?

I work with teams on edge caching for dynamic sites — route classification, cache headers that survive a redesign, purge-on-publish wired into the application, and the monitoring that tells you when hit ratio quietly drops.

If you would rather have this done carefully the first time, you can hire me on Upwork.

The post CDN Setup Without Breaking Dynamic Content appeared first on John Nessime.