Skip to main content
Every error the Darwin API returns has the same shape: an RFC 9457 problem document with Content-Type: application/problem+json. Branch your code on code, show detail to a person, and log request_id.

​
Retry or fix?

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

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

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

​
quota_exceeded

429. The workspace has used its monthly chat API 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.

​
feature_disabled

403. The feature is not switched on. Today this is the chat API, which Darwin enables on request. Contact Darwin 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 with the request_id.

​
Errors outside the API

  • Webhooks: Darwin records your endpoint’s answer, not an error code. See Deliveries.
  • MCP: tool failures come back as a tool result with isError: true and the same sentence you would see in detail. See MCP.