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
/cms/v1/…{ "error": { "code", "message" } }/cms/graphql{ "data", "errors": [{ "message", "path", "locations", "extensions": { "code" } }] }/cms/preview?token=…{ "error": { "code", "message" } }/cms/api/cdn/v1/experiments/collect{ "error": { "code", "message" } }/cms/manage/v1/…{ "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
400codebad_requestsort, 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.400codequery_too_deep400codequery_too_complex401codeunauthorized402codesubscription_inactive403codeforbidden404codenot_found/resolve or the SDK's find… calls where a missing page is normal.405codecreated_in_orbit/organisations: organisations are created in Bifröst Orbit400codeinvalid_idempotency_keyIdempotency-Key header is empty or longer than 255 characters409codeidempotency_key_in_useIdempotency-Key is still running409codeconflictdetails.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 newdocVersion. For a taken value, choose another. Otherwise read the message.410code/resolve only: the page was published once and has been removed. This is an answer, { "data": { "kind": "gone" } }, not an error.410 on your website too413codequery_too_large413codetoo_large422codeidempotency_key_reusedIdempotency-Key was already used in the last 24 hours for a request with a different method, address or body422codevalidation_faileddetails.issues, with path, message and code.path. Send Content-Type: application/json, or the body is ignored.429coderate_limitedRetry-After. Cache answers, and refresh on webhooks instead of polling.500codeinternal_error503codeunavailableRetry-After: 15.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 as522, with no JSON body. Treat any5xxwithout a body asunavailable.
/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.
401CmsAuthErrorAuthExceptionCMSOrbitError).unauthorizedCmsUnauthorizedException402CmsSubscriptionInactiveErrorSubscriptionInactiveExceptionCMSOrbitError).subscriptionInactiveCmsSubscriptionInactiveException404CmsNotFoundErrorNotFoundExceptionCMSOrbitError).notFoundCmsNotFoundException429CmsRateLimitError, with retryAfterRateLimitExceptionCMSOrbitError).rateLimited(retryAfter:)CmsRateLimitedException, with retryAfter5xx, after retriesCmsUnavailableErrorUnavailableExceptionCMSOrbitError).server(status:)CmsServerExceptionCmsUnavailableErrorUnavailableExceptionCMSOrbitError).unavailableCmsServerExceptionCmsErrorCmsExceptionCMSOrbitError).http(status:code:)CmsOrbitExceptionerrorsCmsError, with the first error's codeCmsExceptionCMSOrbitError).graphQL(code:)CmsOrbitException- One base class: every JavaScript error extends
CmsError, every PHP exception extendsBifrostOrbit\Cms\Exception\CmsException, and every Kotlin exception extendsCmsOrbitException. Each has the HTTPstatusand the API'scode(errorCodein PHP). Swift'sCMSOrbitErrorhasstatusandcode. - Retries: the SDKs retry
5xxanswers and failed connections before giving up. They never retry4xxanswers, including402. - GraphQL: in JavaScript, a missing page in a GraphQL answer throws
CmsErrorwithcodenot_found, notCmsNotFoundError. Checkerror.codethere. - 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: truewithout a secret key. JavaScript and PHP throw them as plain errors with a message (InvalidArgumentExceptionandLogicExceptionin PHP). Swift has.invalidAPIKey,.secretKeyNotAllowed,.previewKeyRequiredand.invalidURL. See Troubleshooting your website for each message. - Answers that cannot be read: Swift throws
.decoding, KotlinCmsDecodingException, and PHPCmsExceptionwithinvalid_response. - Previews:
checkPreviewin JavaScript answers{ valid: false, path: null }for any answer other than success, including a5xx, instead of throwing. PHP answersnullfor a refused token and throwsUnavailableExceptionfor a5xx.
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, 503Retry-After500, other 5xx, no answer409 version conflict4024xxWas this page helpful?