> ## Documentation Index > Fetch the complete documentation index at: https://docs.meetdarwin.ai/llms.txt > Use this file to discover all available pages before exploring further. # API errors > Every Darwin API error code, what it means and what to do: the RFC 9457 problem document, HTTP statuses, request ids and which errors are safe to retry. Every error the Darwin API returns has the same shape: an [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) problem document with `Content-Type: application/problem+json`. Branch your code on `code`, show `detail` to a person, and log `request_id`. ```json theme={null} { "type": "https://docs.meetdarwin.ai/api-reference/errors#insufficient_scope", "title": "Insufficient scope", "status": 403, "code": "insufficient_scope", "detail": "This key needs the contacts:read scope.", "request_id": "req_8m2k4p0q1x7z9c3v5b6n" } ``` | Field | What it holds | | - | - | | `type` | A link to this page at the code's own section | | `title` | A short, fixed name for the code | | `status` | The HTTP status, repeated | | `code` | The stable, machine-readable reason. New codes may be added; existing ones do not change meaning. | | `detail` | A sentence for a person, specific to this request. Its wording can change; don't parse it. | | `param` | When one input caused the error, its name, for example `limit`, `email`, `buttons[0].label` or the `Idempotency-Key` header | | `request_id` | The same id as the `X-Request-Id` header. Quote it to Darwin support. | ## Retry or fix? | Status | Retry? | | - | - | | `400`, `401`, `402`, `403`, `404`, `405`, `413`, `422` | No. Fix the request, key or workspace first. | | `409` | Depends on the code: retry `idempotency_key_in_use` after a few seconds; re-read and resend for `conflict`. | | `429` | Yes, after the `Retry-After` header's seconds (`rate_limited`); `quota_exceeded` waits for the next month. | | `500`, `502` | Yes, with backoff, and with the same `Idempotency-Key` on writes. | ## Error codes ### authentication\_required **401.** The request had no `Authorization: Bearer …` header, or it was not in that form. Send your key as `Authorization: Bearer dk_live_…`. A key in a query string or another header is ignored. ### invalid\_api\_key **401.** The key is not valid: it was revoked, mistyped, cut short, or belongs to an AI app connection that expired. Check the key's first characters against the list in **Settings → API**. If it shows **Revoked**, or you can't find it, create a new key. Darwin answers revoked, expired and unknown keys the same way on purpose. ### insufficient\_scope **403.** The key is valid but lacks the scope this endpoint needs. `detail` and the `WWW-Authenticate` header name the scope. Create a key with that scope in **Settings → API** (scopes on an existing key can't be changed). See [Scopes](/api-reference/authentication#scopes). ### payment\_required **402.** The workspace has to finish adding a card before the API can be used, for example because a paid plan was chosen at sign-up and checkout was never completed. An owner signs in to Darwin and completes the card step. Retrying before then returns the same error. ### invalid\_request **400** (or **413** when the body is too large). The request could not be accepted as sent: invalid JSON, an unknown or missing field, a value out of range, an unknown event type, a malformed `starting_after` cursor, a bad date in `updated_since`, an `Idempotency-Key` that is too long, or a field that breaks a rule such as a webhook URL that isn't HTTPS. Read `detail` and `param`, which name the input and the rule. Request bodies are strict: a field the endpoint does not take is refused rather than ignored, so a typo fails loudly. ### not\_found **404.** No object with that id exists in this workspace. It may have been deleted or erased, the id may belong to another workspace, or it may be the wrong kind of id (a `ct_` contact id where a `conv_` conversation id belongs). Check the id and the key's workspace with `GET /me`. ### conflict **409.** The request clashes with the current state. Examples: * Another contact already has this `external_id`. * `PATCH /appearance` sent a `revision` that is no longer current, because someone saved the appearance since you read it. * The chat cannot be switched on yet, or the chat API was used while the chat is switched off. * The workspace already has the maximum number of chat buttons. Read the object again, resolve the clash, then send the request again. ### idempotency\_key\_reused **422.** This `Idempotency-Key` was already used for a different request (a different method, path or body). Use a new key for each distinct request. Reuse a key only to retry exactly the same request. See [Idempotency](/api-reference/idempotency). ### idempotency\_key\_in\_use **409.** A request with this `Idempotency-Key` is still being processed. Wait a few seconds and retry with the same key. You will get the first request's response once it finishes. ### rate\_limited **429.** The key made more requests in the current minute than its plan allows. Wait for the number of seconds in `Retry-After`, then retry. See [Rate limits](/api-reference/rate-limits). ### quota\_exceeded **429.** The workspace has used its monthly [chat API](/api-reference/chat-api#monthly-allowance) conversations. `Retry-After` gives the seconds until the next calendar month, when the allowance starts again. Do not retry before then; a bigger plan has a bigger allowance. ### unsupported\_version **400.** The `Darwin-Version` header names a version this API does not have. Send `Darwin-Version: 2026-10-12` or leave the header out. See [Versioning](/api-reference/introduction#versioning). ### feature\_disabled **403.** The feature is not switched on. Today this is the [chat API](/api-reference/chat-api), which Darwin enables on request. [Contact Darwin](/help/contact) to ask for it. Retrying won't help. ### unprocessable **422.** The request is well formed but a product rule refuses it. For example, applying an opening as an experiment's winner before it has the evidence Darwin requires, or pausing or resuming a test whose state doesn't allow it. `detail` says which rule. These are the same rules the buttons in **Experiments** follow. ### internal\_error **500** (or **502** when the agent could not answer a chat API message). Something went wrong on Darwin's side. Retry with backoff. On a write, send the same `Idempotency-Key` so a retry can't apply twice; a failed request's key is released so the retry runs. If it keeps happening, [contact Darwin](/help/contact) with the `request_id`. ## Errors outside the API * **Webhooks**: Darwin records your endpoint's answer, not an error code. See [Deliveries](/api-reference/webhooks#check-deliveries-and-send-again). * **MCP**: tool failures come back as a tool result with `isError: true` and the same sentence you would see in `detail`. See [MCP](/api-reference/mcp). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.