Errors

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.

API

Data

Deployment

MCP

SDKs

CLI

Admin

Additional Resources

HTTP errors

Action states

Request IDs

​HTTP errors

​Action states

​Request IDs

HTTP errors

Action states

Request IDs