# 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.

Source: https://docs.bifrostorbit.com/cms/developers/error-codes/

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

| API | Address | Error shape |
| --- | --- | --- |
| Delivery | `/cms/v1/…` | `{ "error": { "code", "message" } }` |
| GraphQL | `/cms/graphql` | `{ "data", "errors": [{ "message", "path", "locations", "extensions": { "code" } }] }` |
| Preview | `/cms/preview?token=…` | `{ "error": { "code", "message" } }` |
| Experiments collector | `/cms/api/cdn/v1/experiments/collect` | `{ "error": { "code", "message" } }` |
| Management | `/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

| Status | `code` | APIs | Means | Fix |
| --- | --- | --- | --- | --- |
| `400` | `bad_request` | All | 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. | Read the message, which names the part that is wrong, and fix the request. Do not retry unchanged. |
| `400` | `query_too_deep` | GraphQL | The query nests more than 10 levels | Split it into several queries |
| `400` | `query_too_complex` | GraphQL | The query asks for more than 300 fields, counting aliases and fragments | Ask for fewer fields, or split it |
| `401` | `unauthorized` | All | 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. | 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` | `subscription_inactive` | Delivery, GraphQL | The organisation's CMS Orbit trial or plan has ended, so delivery is paused. Nothing is deleted. | 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` | `forbidden` | Management | 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. | Ask an admin for a role with the permission, use a token that may write, or ask an owner to upgrade. |
| `404` | `not_found` | All | 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. | Check the address, key, region and language. Use `/resolve` or the SDK's `find…` calls where a missing page is normal. |
| `405` | `created_in_orbit` | Management | `POST /organisations`: organisations are created in Bifröst Orbit | Create it in Bifröst Orbit |
| `400` | `invalid_idempotency_key` | Management | The `Idempotency-Key` header is empty or longer than 255 characters | Send a unique value of 1 to 255 characters, such as a UUID |
| `409` | `idempotency_key_in_use` | Management | A request with the same `Idempotency-Key` is still running | Wait a moment, then retry with the same key |
| `409` | `conflict` | Management | 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 | For a version conflict, read again and retry with the new `docVersion`. For a taken value, choose another. Otherwise read the message. |
| `410` | None | Delivery | `/resolve` only: the page was published once and has been removed. This is an answer, `{ "data": { "kind": "gone" } }`, not an error. | Answer `410` on your website too |
| `413` | `query_too_large` | GraphQL | The query is longer than 20,000 characters | Shorten it, or split it |
| `413` | `too_large` | Experiments collector | Too many events in one request | Send smaller batches. The SDK does. |
| `422` | `idempotency_key_reused` | Management | The `Idempotency-Key` was already used in the last 24 hours for a request with a different method, address or body | Send a new key for a new request |
| `422` | `validation_failed` | Management | The body does not match the endpoint's schema. Each problem is in `details.issues`, with `path`, `message` and `code`. | Fix the fields named in `path`. Send `Content-Type: application/json`, or the body is ignored. |
| `429` | `rate_limited` | Delivery, GraphQL, experiments collector | 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. | Wait the seconds in `Retry-After`. Cache answers, and refresh on webhooks instead of polling. |
| `500` | `internal_error` | All | Something failed on our side | Try again after a moment. If it keeps happening, tell us the time and the address. |
| `503` | `unavailable` | All | CMS Orbit is restarting or cannot be reached, after the router has waited 30 seconds. The answer has `Retry-After: 15`. | 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.

| Status | JavaScript | PHP | Swift (`CMSOrbitError`) | Kotlin |
| --- | --- | --- | --- | --- |
| `401` | `CmsAuthError` | `AuthException` | `.unauthorized` | `CmsUnauthorizedException` |
| `402` | `CmsSubscriptionInactiveError` | `SubscriptionInactiveException` | `.subscriptionInactive` | `CmsSubscriptionInactiveException` |
| `404` | `CmsNotFoundError` | `NotFoundException` | `.notFound` | `CmsNotFoundException` |
| `429` | `CmsRateLimitError`, with `retryAfter` | `RateLimitException` | `.rateLimited(retryAfter:)` | `CmsRateLimitedException`, with `retryAfter` |
| `5xx`, after retries | `CmsUnavailableError` | `UnavailableException` | `.server(status:)` | `CmsServerException` |
| Not reached, or timed out | `CmsUnavailableError` | `UnavailableException` | `.unavailable` | `CmsServerException` |
| Any other status | `CmsError` | `CmsException` | `.http(status:code:)` | `CmsOrbitException` |
| GraphQL `errors` | `CmsError`, with the first error's code | `CmsException` | `.graphQL(code:)` | `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](https://docs.bifrostorbit.com/cms/developers/troubleshooting/) 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`.

```ts
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](https://docs.bifrostorbit.com/cms/developers/sdk/), [PHP](https://docs.bifrostorbit.com/cms/developers/sdk-php/), [Swift](https://docs.bifrostorbit.com/cms/developers/sdk-swift/) and [Kotlin](https://docs.bifrostorbit.com/cms/developers/sdk-kotlin/).

## Retry or not

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