Every Colophon route fails the same way, whether the refusal comes from a handler, a permission check or the server’s own middleware: an HTTP status and one JSON envelope. This page lists what can be in it, so a client can decide what to do without reading the message. (GraphQL is the one exception once a document runs: its errors are GraphQL errors carrying the same codes.)
The envelope
Section titled “The envelope”{ "error": { "code": "conflict", "message": "another release committed first: the environment is now at generation 1; look again, then publish", "details": { "reason": "generation_moved", "pointer": "" }, "request_id": "01a1ee8d-f89b-7591-9a1a-f7305e062c87" }}| Member | Always there | What it is |
|---|---|---|
code |
Yes | The kind of failure, from a fixed list (below). Renaming one is a breaking change |
message |
Yes | A sentence safe to show a person. It may change between versions: never branch on it |
details |
No | Machine-readable detail: reason, pointer and, for some reasons, more (below) |
request_id |
Yes | The same value as the x-request-id response header. Quote it when you report a problem: the server’s logs find the request by it |
Branch on code, then on details.reason. code says what kind of thing went wrong (a conflict, a
validation failure); reason says which rule. Unknown reasons will appear as Colophon grows, so treat one you
don’t know by its code.
You may send your own x-request-id (1 to 64 characters of letters, digits, ., _ and -), and the server
uses it instead of making one, so a request can be followed from your logs into Colophon’s:
curl -i "https://cms.example.com/api/v1/projects/$PROJECT/environments/production/collections/recipes/entries/not-a-uuid" \ -H "Authorization: Bearer $COLOPHON_TOKEN" \ -H "x-request-id: build-4711.fetch-recipes"HTTP/1.1 404 Not Foundcontent-type: application/jsonx-request-id: build-4711.fetch-recipescontent-length: 99date: Wed, 18 Nov 2026 14:47:12 GMT
{ "error": { "code": "not_found", "message": "no such resource", "request_id": "build-4711.fetch-recipes" }}An id that breaks those rules is replaced with a fresh one.
Codes and statuses
Section titled “Codes and statuses”| Status | code |
Meaning |
|---|---|---|
400 |
bad_request |
A malformed request no more specific code covers, such as an If-Match or Idempotency-Key header in the wrong form |
400 |
malformed_json |
The body isn’t valid JSON, or holds a member the route doesn’t take. The message says where |
400 |
sign_in_failed |
A sign-in failed, was cancelled, or its state ran out or was already used. Deliberately says no more |
401 |
unauthorized |
No credential, or one that is malformed, unknown, revoked or ended |
403 |
forbidden |
Signed in, but not allowed; details.reason says why |
404 |
not_found |
No such thing, or one you may not see: the two look the same |
404 |
route_not_found |
No route has this path |
405 |
method_not_allowed |
The path exists, not for this method; the Allow header lists the ones it takes |
409 |
conflict |
The request conflicts with the current state; details.reason says how |
410 |
gone |
Published content that has been taken down (delivery), or a preview whose publish request has since been published (preview_published) |
413 |
payload_too_large |
The body is over the server’s limit (21 MiB by default, COLOPHON_MAX_BODY_BYTES) |
415 |
unsupported_media_type |
The body needs Content-Type: application/json |
422 |
validation_failed |
Well-formed, but it breaks a rule; details says which, and where |
428 |
precondition_required |
A required If-Match or Idempotency-Key header is missing; the message names it |
429 |
rate_limited |
Too many requests or attempts; Retry-After says how many seconds to wait |
500 |
internal |
A bug or an unexpected failure. The cause is logged, never returned |
503 |
unavailable |
Temporarily unable to serve: at capacity, or a service it needs is down |
504 |
deadline_exceeded |
The server didn’t produce an answer within its request deadline (10 seconds by default, COLOPHON_REQUEST_TIMEOUT_MS) |
Reasons, by situation
Section titled “Reasons, by situation”details.reason is a stable code. These are the ones you are most likely to meet.
Signing in and credentials
Section titled “Signing in and credentials”| Status | reason |
When |
|---|---|---|
401 |
(none) | Every credential problem is the same unauthorized, so a guesser learns nothing |
401 |
preview_invalid, preview_revoked, preview_expired |
A preview token that is missing, unknown, ended from the Studio or out of time (/preview/v1 only) |
403 |
api_token_not_allowed |
An API token on a route kept for people: members, roles, tokens, the activity log, scheduling, previews |
403 |
csrf_token_invalid |
A write with the Studio’s session cookie but without the matching X-CSRF-Token |
403 |
origin_not_allowed |
A cookie-signed write from an Origin the server doesn’t trust |
403 |
browser_session_required |
Approving a CLI sign-in with anything but a browser session |
403 |
account_disabled |
A site user whose account an owner turned off (said only after the right password) |
400 |
sign_in_failed (as the code) |
A wrong password, an unknown account, or too many guesses from your address: all look the same |
Permissions
Section titled “Permissions”| Status | reason |
When |
|---|---|---|
403 |
missing_permission |
Your role or token lacks a permission here; details.permission names it, such as content.publish |
403 |
cannot_grant |
Giving a role, member or token a power you don’t have yourself |
403 |
agent_self_review |
An API token approving a publish request that a token sent for review |
403 |
budget_exceeded |
Over a token’s documents_per_day or max_concurrent_jobs (limits) |
403 |
fields_not_readable, titles_not_readable |
An export, or a list of titles, that needs fields your role can’t read |
422 |
field_not_permitted |
A write that changes a field your role may not change; the pointer names it |
422 |
field_not_readable |
A query that filters or sorts on a field your role can’t read |
Preconditions: lost answers and lost updates
Section titled “Preconditions: lost answers and lost updates”| Status | reason |
When | Comes with |
|---|---|---|---|
428 |
(none) | No Idempotency-Key on a write that needs one, or no If-Match on a save |
|
400 |
(none) | If-Match: *, or an If-Match or Idempotency-Key in the wrong form |
|
409 |
idempotency_key_reused |
The same key with a different request | |
409 |
stale_revision |
Saving an entry on a revision that is no longer its draft | ETag: the current revision |
409 |
stale_version |
Changing a content type or component on an old version | ETag: "v<version>" now |
409 |
stale_changeset |
Acting on a publish request whose entries changed since you loaded it | ETag: its hash now |
409 |
stale_stages |
Changing review stages from an old list | ETag: the list now |
409 |
stale_role |
Changing a role on an old version | ETag: "v<version>" now |
409 |
plan_moved |
Acting on a schema migration plan that changed | ETag: its hash now |
The management API’s Idempotency-Key and If-Match sections show these at work.
Conflicts with what is stored
Section titled “Conflicts with what is stored”| Status | reason |
When | Comes with |
|---|---|---|---|
409 |
slug_taken, value_taken |
Another entry has this URL name, or this value in a field that must be unique | entries: the one that has it, when known |
409 |
still_referenced |
Deleting something other entries still link to | referenced_by: those entries |
409 |
entry_in_changeset |
Deleting an entry a publish request would publish | changesets: those requests |
409 |
single_exists |
A second entry in a content type that holds only one | |
409 |
locale_taken |
A translation into a language the entry already has | |
409 |
last_owner |
Removing or demoting a project’s last owner | |
409 |
role_in_use |
Deleting a role members still hold | |
409 |
migration_in_progress |
Changing or deleting a content type while a schema migration of it runs | |
422 |
needs_migration |
A content type change that stored entries wouldn’t fit | entries (the first 20) and total |
Validation
Section titled “Validation”Validation failures are 422 validation_failed, and details.pointer is a JSON Pointer to the place in
your request body that is wrong (/minutes, /fields/0); an empty pointer means the whole body.
reason |
When |
|---|---|
missing_field, unknown_field, wrong_type |
A required field is absent, a field isn’t in the content type, or a value is the wrong kind |
too_long, too_short, out_of_range, too_many |
A value is outside its limits |
not_an_option, pattern_mismatch, invalid_datetime |
A value isn’t one of the choices, doesn’t match the field’s pattern, or isn’t a date |
reference_not_found, asset_not_found |
A link to an entry, or an upload, that doesn’t exist here |
unsafe_link, unknown_node, unknown_mark, invalid_content, too_many_nodes, too_many_images |
A rich-text document Colophon won’t store |
field_not_indexed, invalid_op |
A query filters or sorts on a field that isn’t filterable, or uses an operator its kind doesn’t take |
invalid_cursor, foreign_cursor |
A cursor that is damaged, or belongs to another query |
invalid_generation |
A release that doesn’t exist (?generation=, base_generation) |
ambiguous_local_time, skipped_local_time |
A scheduled time the clocks show twice, or skip, in its time zone; candidates lists the two instants to choose from |
invalid_url, invalid_kind, invalid_name, invalid_location |
A website connection refused |
invalid_token_name, unknown_token_kind, invalid_expiry, permissions_required, permissions_not_applicable, too_many_tokens, invalid_limit, limits_empty |
An API token refused |
too_large, too_deep, too_complex, fragment_cycle |
A GraphQL document over its bounds |
Publishing
Section titled “Publishing”| Status | reason |
When | Comes with |
|---|---|---|---|
409 |
generation_moved |
Another release committed after the base_generation you sent |
Colophon-Generation: the release now |
409 |
not_approved |
Publishing a request that hasn’t been approved | |
409 |
approval_expired |
The approval ran out; it needs reviewing again | |
409 |
entries_moved_on |
An entry moved on after the request pinned it; refresh and review again | |
409 |
already_published |
Publishing a request a second time | |
409 |
references_unpublished |
An entry links to one that isn’t published; publish both together | |
409 |
revision_outdated |
A pinned revision no longer fits its content type | entries, with each one’s problem |
422 |
stage_required, unknown_stage |
An approval that must, or can’t, name a review stage |
Rate limits and capacity
Section titled “Rate limits and capacity”| Status | reason |
When | Comes with |
|---|---|---|---|
429 |
rate_limited |
Over a request limit, a token’s requests_per_minute, or a live event stream cap |
Retry-After in seconds |
429 |
(none) | Too many sign-in links asked for, or setup code attempts; the message counts in minutes | Retry-After in seconds |
503 |
(none) | No database connection or password-hashing slot came free in time: “the server is busy” | Retry-After: 1 |
503 |
work_full, payload_full |
The project’s unfinished background work, or the server’s, is at its bound | Retry-After: 5 |
503 |
(none) | A server carrying as many event streams or MCP sessions as it can, or a service it needs (the object store, the identity provider) unreachable |
See Rate limits for what is counted.
What details can carry
Section titled “What details can carry”reason and pointer are in every details. Some reasons add more:
| Member | With | What it holds |
|---|---|---|
permission |
missing_permission |
The permission you lack, as roles name it |
entries |
needs_migration, slug_taken, value_taken, revision_outdated |
Entries in the way: entry, title, state (draft, published or pinned) and, for content changes, problem (reason, pointer into the entry’s content, message) |
total |
needs_migration |
How many entries are in the way in all, when entries lists only the first 20 |
content_type |
A component change | The content type whose entries are in the way |
referenced_by |
still_referenced |
The entries that still link to it: entry_id, collection, field, in_draft, published |
changesets |
entry_in_changeset |
The publish requests that would publish it: id, title, scheduled |
candidates |
ambiguous_local_time, skipped_local_time |
The two instants, earlier first, as RFC 3339 |
Headers that come with errors
Section titled “Headers that come with errors”| Header | On | Use it to |
|---|---|---|
x-request-id |
Every response | Quote the request; it equals request_id |
Retry-After |
429, and 503 when the server is busy or its work is full |
Wait that many seconds before trying again |
ETag |
409 stale refusals (stale_revision, stale_version, …) |
Know the current version: read it, merge your change, send that value as If-Match |
Colophon-Generation |
409 generation_moved, and every delivery answer |
Know the release the environment is at now |
Allow |
405 |
See the methods the path takes |
Cache-Control: no-store |
410 gone |
Keep caches from remembering a take-down |
Real refusals
Section titled “Real refusals”A write without an Idempotency-Key:
curl -i -X POST "https://cms.example.com/api/v1/projects/$PROJECT/environments/production/collections/recipes/entries" \ -H "Authorization: Bearer $COLOPHON_TOKEN" \ -H "Content-Type: application/json" \ -d '{"dish": "Scones", "minutes": 25}'HTTP/1.1 428 Precondition Requiredcontent-type: application/jsonx-request-id: 01a1ef20-4818-72a2-a398-0954b2e12443content-length: 151date: Wed, 18 Nov 2026 14:47:12 GMT
{ "error": { "code": "precondition_required", "message": "this request needs an Idempotency-Key header", "request_id": "01a1ef20-4818-72a2-a398-0954b2e12443" }}Publishing on top of a release that is no longer the newest. The environment was at release 1; the
request said "base_generation": 0:
HTTP/1.1 409 Conflictcontent-type: application/jsoncolophon-generation: 1x-request-id: 01a1ee8d-f89b-7591-9a1a-f7305e062c87content-length: 244date: Wed, 18 Nov 2026 12:07:24 GMT
{ "error": { "code": "conflict", "message": "another release committed first: the environment is now at generation 1; look again, then publish", "details": { "reason": "generation_moved", "pointer": "" }, "request_id": "01a1ee8d-f89b-7591-9a1a-f7305e062c87" }}Look at what release 1 changed, then publish again with "base_generation": 1.
A content type change that stored entries wouldn’t fit. Limiting dish to 10 characters, with a
token that may change content types:
curl -i -X PUT "https://cms.example.com/api/v1/projects/$PROJECT/environments/production/content-types/recipes" \ -H "Authorization: Bearer $COLOPHON_TOKEN" \ -H "Content-Type: application/json" \ -H 'If-Match: "v3"' \ -H "Idempotency-Key: errors-shorter-dish-1" \ -d '{"name": "Recipes", "title_field": "dish", "fields": [ {"id": "dish", "label": "Dish", "type": "text", "required": true, "max_chars": 10, "multiline": false}, {"id": "minutes", "label": "Minutes", "type": "number", "required": false, "integer": true, "index": true}, {"id": "method", "label": "Method", "type": "rich_text", "required": false}]}'Response: 422, naming each entry in the way and why
HTTP/1.1 422 Unprocessable Entitycontent-type: application/jsonx-request-id: 01a1ef20-4828-71ca-bc42-dbef0b4e05c7content-length: 494date: Wed, 18 Nov 2026 14:47:12 GMT
{ "error": { "code": "validation_failed", "message": "this change to `dish` would make stored content invalid: 1 entry is in the way; change them first, or keep the old definition", "details": { "reason": "needs_migration", "pointer": "/fields/0", "entries": [ { "entry": "01a1ef20-4597-76f8-bae6-0b7a237cec78", "title": "Ginger biscuits", "state": "draft", "problem": { "reason": "too_long", "pointer": "/dish", "message": "Dish is at most 10 characters" } } ], "total": 1 }, "request_id": "01a1ef20-4828-71ca-bc42-dbef0b4e05c7" }}details.pointer points into the request body (the first field), and each entry’s problem.pointer into
that entry’s content. Nothing was changed.
A method the path doesn’t take:
curl -i -X DELETE "https://cms.example.com/api/v1/projects/$PROJECT/environments/production/destinations" \ -H "Authorization: Bearer $COLOPHON_TOKEN"HTTP/1.1 405 Method Not Allowedcontent-type: application/jsonx-request-id: 01a1ef20-483e-73a1-b62b-4cdc22e95c60allow: GET,HEAD,POSTcontent-length: 122date: Wed, 18 Nov 2026 14:47:12 GMT
{ "error": { "code": "method_not_allowed", "message": "method not allowed", "request_id": "01a1ef20-483e-73a1-b62b-4cdc22e95c60" }}More refusals are shown where they belong: 401 and 403 on Authentication,
409 and 422 on Management API, 410 on Delivery API,
and 429 on Rate limits.
Retrying
Section titled “Retrying”Some failures say nothing was decided, and the same request may go again. Others will answer the same way every time until something changes.
| Retry? | Failures |
|---|---|
| Yes, as it is | No answer at all (a dropped connection, a client timeout), 429, 503, 504, 500 |
| After reading again | 409 stale refusals and generation_moved: read the current version (the ETag or Colophon-Generation header names it), merge or check, then send a new request |
| No | Every other 4xx: fix the request first |
Two rules make retrying writes safe:
- Wait as told. After a
429or a503withRetry-After, wait at least that many seconds. Without one, back off: wait a second, then two, then four, with some randomness, and give up after a few tries. - Keep the
Idempotency-Key. A write that timed out may have happened. Send the retry with the same key and the same body: if the first one committed, you get its answer back (withidempotent-replayed: true) and nothing is written twice; if it didn’t, it happens now. Only successes are remembered, so after a refusal you fix the request and may use a new key.
The SDK does the reading for you: every failure is an ApiError with status, code, reason,
pointer, requestId, etag (the current version on a conflict), retryAfterMs (Retry-After in
milliseconds, at most a minute) and retryable, which is true for no answer, 429 and any 5xx: the “yes,
as it is” row above.
import { ApiError } from '@colophon-cms/sdk';
try { await save();} catch (error) { if (error instanceof ApiError && error.retryable) { await new Promise((resolve) => setTimeout(resolve, error.retryAfterMs ?? 1_000)); await save(); // the same call, with the same idempotency key } else { throw error; }}Was this page helpful?
Either answer opens a short issue on GitHub, so you can say what worked or what was missing.
Colophon home · the product, its blog and how to try it.