> ## Documentation Index
> Fetch the complete documentation index at: https://docs.darwin.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> Understand Darwin HTTP errors and structured action states.

Darwin uses standard HTTP status codes for transport and authorization failures. A successful HTTP response may still contain a structured action state when more user input or authority is required.

## HTTP errors

| Status | Meaning                                                                   | What to do                                                         |
| ------ | ------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| `400`  | The request is malformed or fails validation.                             | Check the response details and the endpoint schema.                |
| `401`  | The API key, session, or OAuth grant is missing or expired.               | Authenticate again or replace the credential.                      |
| `403`  | The credential is valid but lacks the required scope or authority.        | Use an appropriately scoped key or request access.                 |
| `404`  | The resource does not exist or is not visible to the authenticated owner. | Verify the identifier and ownership context.                       |
| `409`  | The request conflicts with current state or an idempotent operation.      | Read the current resource before retrying.                         |
| `429`  | The client is sending requests too quickly.                               | Respect `Retry-After` and use exponential backoff.                 |
| `5xx`  | Darwin or an upstream provider could not complete the request.            | Retry transient failures with backoff and preserve the request ID. |

## Action states

Reviewed tools can return a non-error state instead of performing an unsafe or impossible action:

* `request_required` — the proposed action created a request that needs attention
* `connection_required` — the owner must connect the required service
* `insufficient_authority` — the active agent or credential cannot perform the action
* `provider_unavailable` — an external provider is temporarily unavailable

Clients should display the supplied summary and available actions instead of treating these states as successful execution.

## Request IDs

Send an idempotency or request ID when the endpoint supports one. Preserve Darwin's response correlation ID in logs and support requests, but never log API keys, OAuth tokens, or provider credentials.