Skip to content

Error codes

Every HTTP status and error code the delivery, GraphQL, preview and management APIs return, the SDK error for each in JavaScript, PHP, Swift and Kotlin, what it means and the fix.

Reference8 min read

Every CMS Orbit API reports errors with an HTTP status and a short code. Write your code against the status and the code: they stay the same, while messages can be reworded and, in the management API, translated.

Where the code is

Delivery
Address
/cms/v1/…
Error shape
{ "error": { "code", "message" } }
GraphQL
Address
/cms/graphql
Error shape
{ "data", "errors": [{ "message", "path", "locations", "extensions": { "code" } }] }
Preview
Address
/cms/preview?token=…
Error shape
{ "error": { "code", "message" } }
Experiments collector
Address
/cms/api/cdn/v1/experiments/collect
Error shape
{ "error": { "code", "message" } }
Management
Address
/cms/manage/v1/…
Error shape
{ "error": { "code", "message", "details" } }

details is there when there is more to read, such as the fields that failed. In GraphQL, the HTTP status comes from the first error.

Every code

400
code
bad_request
APIs
All
Means
The request is malformed or does not make sense here. Delivery: an unknown sort, a bad filter[…] name or an unknown include. GraphQL: no query, a query that does not parse or match the schema, variables that are not an object. Preview: no token. Management: invalid JSON, a field value that breaks the content type's rules (in details), or an action the item's state does not allow.
Fix
Read the message, which names the part that is wrong, and fix the request. Do not retry unchanged.
400
code
query_too_deep
APIs
GraphQL
Means
The query nests more than 10 levels
Fix
Split it into several queries
400
code
query_too_complex
APIs
GraphQL
Means
The query asks for more than 300 fields, counting aliases and fragments
Fix
Ask for fewer fields, or split it
401
code
unauthorized
APIs
All
Means
No key or token, or one that is unknown, deleted, revoked or expired. Delivery and GraphQL also: a public key asking for drafts, a secret key from a browser on another website, a region or language the key may not read. Preview: an invalid or expired preview token. Management: the token's person no longer has access, or a session-only endpoint called with a token.
Fix
Check the key in Configuration › API keys, or the token on Management tokens: its environment, regions, languages and expiry. Create a new one if in doubt. Reopen previews from the editor.
402
code
subscription_inactive
APIs
Delivery, GraphQL
Means
The organisation's CMS Orbit trial or plan has ended, so delivery is paused. Nothing is deleted.
Fix
An owner chooses a plan under Billing in Bifröst Orbit. Delivery answers again within seconds. Show a paused page meanwhile; do not retry in a loop.
403
code
forbidden
APIs
Management
Means
The token's person lacks the permission, the token is read only, the plan does not include the feature, or a plan limit is reached. The message names the permission or the limit.
Fix
Ask an admin for a role with the permission, use a token that may write, or ask an owner to upgrade.
404
code
not_found
APIs
All
Means
Nothing at the address, or no item, menu, global entry, taxonomy, region, language, organisation or endpoint with that key. The message names which. A management token used for another organisation gets this too.
Fix
Check the address, key, region and language. Use /resolve or the SDK's find… calls where a missing page is normal.
405
code
created_in_orbit
APIs
Management
Means
POST/organisations: organisations are created in Bifröst Orbit
Fix
Create it in Bifröst Orbit
400
code
invalid_idempotency_key
APIs
Management
Means
The Idempotency-Key header is empty or longer than 255 characters
Fix
Send a unique value of 1 to 255 characters, such as a UUID
409
code
idempotency_key_in_use
APIs
Management
Means
A request with the same Idempotency-Key is still running
Fix
Wait a moment, then retry with the same key
409
code
conflict
APIs
Management
Means
The page changed since you read it (details.currentVersion is its version now, details.expected the one you sent), someone has it open, a value is already taken (such as an address, key or slug), or the item is in a state that does not allow this, such as publishing with nothing new
Fix
For a version conflict, read again and retry with the new docVersion. For a taken value, choose another. Otherwise read the message.
410
code
None
APIs
Delivery
Means
/resolve only: the page was published once and has been removed. This is an answer, { "data": { "kind": "gone" } }, not an error.
Fix
Answer 410 on your website too
413
code
query_too_large
APIs
GraphQL
Means
The query is longer than 20,000 characters
Fix
Shorten it, or split it
413
code
too_large
APIs
Experiments collector
Means
Too many events in one request
Fix
Send smaller batches. The SDK does.
422
code
idempotency_key_reused
APIs
Management
Means
The Idempotency-Key was already used in the last 24 hours for a request with a different method, address or body
Fix
Send a new key for a new request
422
code
validation_failed
APIs
Management
Means
The body does not match the endpoint's schema. Each problem is in details.issues, with path, message and code.
Fix
Fix the fields named in path. Send Content-Type: application/json, or the body is ignored.
429
code
rate_limited
APIs
Delivery, GraphQL, experiments collector
Means
Too many requests. Delivery and GraphQL: over 60,000 a minute from one key, or 15,000 from one IP address. The collector counts per IP address.
Fix
Wait the seconds in Retry-After. Cache answers, and refresh on webhooks instead of polling.
500
code
internal_error
APIs
All
Means
Something failed on our side
Fix
Try again after a moment. If it keeps happening, tell us the time and the address.
503
code
unavailable
APIs
All
Means
CMS Orbit is restarting or cannot be reached, after the router has waited 30 seconds. The answer has Retry-After: 15.
Fix
Wait and retry. Websites keep serving cached pages, and the JavaScript SDK falls back to its mirror.

A few more answers come from before a request reaches an endpoint:

  • 308: a delivery address with a trailing slash, such as /cms/v1/content/, redirects. Leave the slash off.
  • Other 5xx: Cloudflare, in front of CMS Orbit, answers some failures itself, such as 522, with no JSON body. Treat any 5xx without a body as unavailable.

/resolve answers 404 with { "data": { "kind": "notFound" } } when nothing was ever published at an address. That is a normal answer too, not an error.

In the SDKs

The SDKs read the delivery, GraphQL and preview APIs. There is no SDK for the management API yet: call it over HTTP.

401
JavaScript
CmsAuthError
PHP
AuthException
Swift (CMSOrbitError)
.unauthorized
Kotlin
CmsUnauthorizedException
402
JavaScript
CmsSubscriptionInactiveError
PHP
SubscriptionInactiveException
Swift (CMSOrbitError)
.subscriptionInactive
Kotlin
CmsSubscriptionInactiveException
404
JavaScript
CmsNotFoundError
PHP
NotFoundException
Swift (CMSOrbitError)
.notFound
Kotlin
CmsNotFoundException
429
JavaScript
CmsRateLimitError, with retryAfter
PHP
RateLimitException
Swift (CMSOrbitError)
.rateLimited(retryAfter:)
Kotlin
CmsRateLimitedException, with retryAfter
5xx, after retries
JavaScript
CmsUnavailableError
PHP
UnavailableException
Swift (CMSOrbitError)
.server(status:)
Kotlin
CmsServerException
Not reached, or timed out
JavaScript
CmsUnavailableError
PHP
UnavailableException
Swift (CMSOrbitError)
.unavailable
Kotlin
CmsServerException
Any other status
JavaScript
CmsError
PHP
CmsException
Swift (CMSOrbitError)
.http(status:code:)
Kotlin
CmsOrbitException
GraphQL errors
JavaScript
CmsError, with the first error's code
PHP
CmsException
Swift (CMSOrbitError)
.graphQL(code:)
Kotlin
CmsOrbitException
  • One base class: every JavaScript error extends CmsError, every PHP exception extends BifrostOrbit\Cms\Exception\CmsException, and every Kotlin exception extends CmsOrbitException. Each has the HTTP status and the API's code (errorCode in PHP). Swift's CMSOrbitError has status and code.
  • Retries: the SDKs retry 5xx answers and failed connections before giving up. They never retry 4xx answers, including 402.
  • GraphQL: in JavaScript, a missing page in a GraphQL answer throws CmsError with code not_found, not CmsNotFoundError. Check error.code there.
  • Before a request: some errors come from the SDK itself, such as a missing key, a secret key in browser code or in an app, or preview: true without a secret key. JavaScript and PHP throw them as plain errors with a message (InvalidArgumentException and LogicException in PHP). Swift has .invalidAPIKey, .secretKeyNotAllowed, .previewKeyRequired and .invalidURL. See Troubleshooting your website for each message.
  • Answers that cannot be read: Swift throws .decoding, Kotlin CmsDecodingException, and PHP CmsException with invalid_response.
  • Previews: checkPreview in JavaScript answers { valid: false, path: null } for any answer other than success, including a 5xx, instead of throwing. PHP answers null for a refused token and throws UnavailableException for a 5xx.
TypeScript
import { CmsError, CmsNotFoundError, CmsRateLimitError, isSubscriptionInactive } from '@bifrost-orbit-cms/sdk'try {  return await cms.getPage('/gear/fjell-gtx-boot', { region: 'no' })} catch (error) {  if (error instanceof CmsNotFoundError) return notFound()  if (isSubscriptionInactive(error)) return pausedPage()  if (error instanceof CmsRateLimitError) console.warn(`Retry in ${error.retryAfter}s`)  if (error instanceof CmsError) console.error(error.status, error.code, error.message)  throw error}

See the SDK pages for each language: JavaScript, PHP, Swift and Kotlin.

Retry or not

429, 503
Retry?
Yes, after Retry-After
500, other 5xx, no answer
Retry?
Yes, a few times with growing waits
409 version conflict
Retry?
Yes, after reading the item again
402
Retry?
No. It answers again once an owner chooses a plan.
Any other 4xx
Retry?
No. Fix the request first.

Was this page helpful?

Read next