More Than 4 Cache Breakpoints in One Request

The mistake

Marking more explicit cache breakpoints in one request than the API will write — usually while giving a long, multi-section prompt several independent anchors (a system section, tool definitions, a reference document, a per-user section) — and assuming every marked boundary gets cached.

Why this happens

Each request can create at most 4 cache writes on GPT-5.6 and later. In implicit mode, the implicit breakpoint at the latest eligible message takes one of those slots, leaving one fewer for your explicit markers. This page used to say the API keeps the newest marked breakpoints and silently drops the rest. OpenAI's current guide states the cap but not which marked breakpoints are written when you exceed it, so this site no longer claims to know — and you shouldn't build on an assumption about it either.

Why it matters

A breakpoint that isn't written doesn't fail loudly. It shows up, if at all, as one section of a long prompt that never earns its expected discount however often it's reused, while neighboring sections cache normally. Every marked breakpoint looks identical in the code that sent it, so the cause is close to invisible without knowing the cap exists.

The fix

Count your breakpoints per request against the cap, remembering the implicit slot. If a prompt genuinely has more independently reusable sections than you can mark, choose the ones with the highest expected reuse and leave the rest unmarked. Switching to explicit-only mode (prompt_cache_options.mode: "explicit") frees the implicit slot and stops volatile content after your last marker from being written at all — it then bills as ordinary input, without the write surcharge. Prompts assembled from chunks written by different people are the usual culprit: each author marks their own boundary and nobody counts the total.

Catching it before the bill does

The usage object offers an indirect check: if cache_write_tokens on a request that marked several sections comes in well below the combined size of those sections, some of them weren't written. A more direct guard lives in your own code — have the prompt builder count the breakpoints it emits per request, and fail a test or log a warning when the count exceeds the cap. That catches the problem at assembly time, where it's cheap to fix.