Errors

Every failure answers with the same JSON shape, whatever caused it. Switch on error.code, never on the message text — messages are localised and may be reworded; codes are part of the contract.

The envelope

json

{
  "message": "Validation failed.",
  "errors": {
    "name": ["The name field is required."]
  },
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Validation failed.",
    "details": {
      "fields": {
        "name": ["The name field is required."]
      }
    }
  },
  "request_id": "483c1c5107978d552c8f634d8b141501"
}

error.code — the machine-readable cause. This is what your code branches on.
error.details — extra context. Field errors for a 422, the required and missing scopes for a 403.
errors — the flat field map, for form libraries that expect it.
request_id — also on the X-Request-ID header. Quote it in a support request and the whole conversation gets shorter.

There is no success field on /v1. The status code already says whether it worked; a boolean that restates it is one more thing that can disagree with reality.

The codes

Code	HTTP	Description	Returned by
`ACCOUNT_SELECTOR_NOT_SUPPORTED`	400	The `X-Account-Id` header is not this key's owner, or `X-Workspace-Id` names another workspace. `details.header` names which.	151 operations
`INVALID_IDEMPOTENCY_KEY`	400	`Idempotency-Key` is present but is not 16–128 letters, digits, `_` or `-`.	80 operations
`UNAUTHENTICATED`	401	Missing, unknown, revoked, expired, rotated-out or IP-blocked API key. The reason is recorded in the request log only.	151 operations
`AGENT_LIMIT_REACHED`	402	The plan limit for agents is already reached.	`POST /v1/chatbots`
`AI_ACTION_LIMIT_REACHED`	402	The plan limit for Call Actions on this agent is already reached.	`POST /v1/actions`
`CHANNEL_LIMIT_REACHED`	402	The chatbot already has as many connected channels as the plan allows (`details.max_connected`).	`POST /v1/chatbots/{chatbotId}/channels/{platform}`
`CHATBOT_BUDGET_EXCEEDED`	402	The chatbot spent its monthly AI budget.	`POST /v1/actions/{id}/test`, `POST /v1/chat`, `POST /v1/chat/stream`
`INTEGRATIONS_NOT_AVAILABLE`	402	The plan does not include channel integrations.	`POST /v1/chatbots/{chatbotId}/channels/{platform}`
`KNOWLEDGE_PLAN_SIZE_EXCEEDED`	402	The plan limit for knowledge size is already reached.	4 operations
`MESSAGE_CREDITS_EXCEEDED`	402	The account has no message credits left this period (`details.resource`, and `details.plan` for an authenticated owner).	`POST /v1/actions/{id}/test`, `POST /v1/chat`, `POST /v1/chat/stream`
`USER_BUDGET_EXCEEDED`	402	The account spent its monthly AI budget.	`POST /v1/actions/{id}/test`, `POST /v1/chat`, `POST /v1/chat/stream`
`ACCOUNT_SUSPENDED`	403	The key owner is banned or inactive.	151 operations
`FORBIDDEN`	403	A policy refused the action, e.g. a key restricted to selected agents that holds the needed permission on none of them.	12 operations
`INSUFFICIENT_SCOPE`	403	The API key lacks a scope this operation requires.	150 operations
`ACTIONS_DISABLED`	404	Call Actions are switched off.	`POST /v1/actions/{id}/test`
`FEATURE_DISABLED`	404	This feature is switched off.	Any request, before an operation is matched
`IMPORT_PROVIDER_UNAVAILABLE`	404	That cloud import provider is not available.	`POST /v1/knowledge/import/cloud`
`MCP_NOT_ENABLED`	404	MCP actions are switched off.	`POST /v1/actions/mcp/discover`
`NOT_FOUND`	404	No resource with that id exists for this key.	117 operations
`ROUTE_NOT_FOUND`	404	The path does not match an operation.	Any request, before an operation is matched
`ACTION_TOOL_NAME_CONFLICT`	409	Could not assign a unique tool name to that action.	`POST /v1/actions`
`CHANNEL_CONNECT_BUSY`	409	Another channel connect for this chatbot is still running; nothing was written. Retry once it finishes.	`POST /v1/chatbots/{chatbotId}/channels/{platform}`
`CHATBOT_NAME_TAKEN`	409	An agent with that name already exists.	`POST /v1/chatbots`, `PATCH /v1/chatbots/{id}`
`COLLECTION_HAS_DATASETS`	409	The collection still contains knowledge sources (`details.dataset_count`).	`DELETE /v1/knowledge/collections/{id}`
`CRAWLER_INACTIVE`	409	The crawler is inactive, so this transition is refused.	5 operations
`CRAWLER_NOT_PAUSED`	409	The crawler is not paused, so this transition is refused.	`POST /v1/crawlers/{id}/resume`, `POST /v1/sitemap_crawlers/{id}/resume`
`CRAWLER_NOT_RUNNING`	409	The crawler is not running, so this transition is refused.	`POST /v1/crawlers/{id}/pause`, `POST /v1/sitemap_crawlers/{id}/pause`
`CRAWLER_RUNNING`	409	The crawler is already running, so this transition is refused.	5 operations
`CRAWLER_TERMINAL`	409	The crawler has finished, so this transition is refused.	`POST /v1/crawlers/queue/cancel`, `POST /v1/crawlers/{id}/cancel`
`CRAWL_NOT_RETRYABLE`	409	This crawl cannot be retried.	`POST /v1/crawlers/{id}/retry`, `POST /v1/sitemap_crawlers/{id}/scan`, `POST /v1/sitemap_crawlers/{id}/retry`
`DATASET_DELETING`	409	The knowledge source is being removed.	8 operations
`DATASET_NOT_UPLOAD_SOURCED`	409	Replacing a file only applies to an uploaded knowledge source.	`POST /v1/knowledge/{id}/replace_file`
`DATASET_NOT_URL_SOURCED`	409	Recrawl only applies to a URL, link or sitemap source.	`POST /v1/knowledge/{id}/recrawl`
`DELIVERY_ALREADY_DELIVERED`	409	The delivery already succeeded. Only a failed delivery can be retried.	`POST /v1/webhook_deliveries/{id}/retry`
`DELIVERY_IN_FLIGHT`	409	A retry is already in progress for this delivery.	`POST /v1/webhook_deliveries/{id}/retry`
`ENDPOINT_URL_ALREADY_REGISTERED`	409	A webhook endpoint with that URL already exists.	`POST /v1/webhook_endpoints`, `PATCH /v1/webhook_endpoints/{id}`
`FILE_BACKS_DATASET`	409	The file still backs a knowledge source (`details.dataset_id`). Remove that source first.	`DELETE /v1/files/{id}`
`IDEMPOTENCY_IN_FLIGHT`	409	A request with the same `Idempotency-Key` is still running. Retry after `Retry-After` seconds.	80 operations
`INGESTION_IN_PROGRESS`	409	Knowledge processing is already running.	`PATCH /v1/knowledge/{id}`, `POST /v1/knowledge/{id}/retry`, `POST /v1/knowledge/{id}/replace_file`
`KNOWLEDGE_NAME_TAKEN`	409	A knowledge source with that name already exists.	`POST /v1/knowledge`, `PATCH /v1/knowledge/{id}`, `POST /v1/knowledge/import/cloud`
`NOTHING_TO_CANCEL`	409	There is no ingest in progress to cancel.	`POST /v1/knowledge/{id}/cancel`
`RECRAWL_IN_PROGRESS`	409	A recrawl is already running.	`POST /v1/knowledge/{id}/recrawl`
`ACTION_LIMIT_REACHED`	422	This agent already has the maximum number of enabled actions.	`POST /v1/actions`, `PATCH /v1/actions/{id}`
`ACTION_TYPE_UNAVAILABLE`	422	That action type is not available.	`POST /v1/actions`
`BLOCKED_DESTINATION`	422	The URL points at a blocked destination.	`POST /v1/webhook_endpoints`, `PATCH /v1/webhook_endpoints/{id}`
`BLOCKED_DOMAIN`	422	The URL host is blocked or not routable.	`POST /v1/crawlers`, `POST /v1/sitemap_crawlers`
`CHALLENGE_BLOCKED`	422	The site answered with a human-verification page instead of the document.	`POST /v1/crawlers`, `POST /v1/sitemap_crawlers`
`CHANNEL_CONNECTION_FAILED`	422	The channel platform rejected the credentials.	`POST /v1/chatbots/{chatbotId}/channels/{platform}`
`CHATBOT_REQUIRED`	422	This knowledge source needs an agent.	`POST /v1/knowledge`, `POST /v1/knowledge/{id}/retry`
`CLOUD_IMPORT_FAILED`	422	None of the picked cloud files could be imported (`error.details.failures`).	`POST /v1/knowledge/import/cloud`
`COLLECTION_NOT_OWNED_BY_CHATBOT`	422	The collection belongs to a different agent than `chatbot_id`.	`POST /v1/knowledge`, `POST /v1/knowledge/import/cloud`, `POST /v1/knowledge/collections/{id}/datasets`
`CONTENT_TOO_LARGE`	422	The document is larger than the crawl size cap.	`POST /v1/crawlers`, `POST /v1/sitemap_crawlers`
`CORRUPT_CONTENT_ENCODING`	422	The response body could not be decoded.	`POST /v1/crawlers`, `POST /v1/sitemap_crawlers`
`CRAWLING_ERROR`	422	The crawl could not start.	`POST /v1/crawlers`, `POST /v1/sitemap_crawlers`
`EXPORT_TOO_LARGE`	422	The filtered export is over the row cap (`details.limit`, `details.rows`, `details.max_rows`). Narrow the filters.	`GET /v1/customers/export`
`HTTPS_REQUIRED`	422	The webhook URL must use HTTPS.	`POST /v1/webhook_endpoints`, `PATCH /v1/webhook_endpoints/{id}`
`IDEMPOTENCY_KEY_REUSED`	422	The `Idempotency-Key` was already used with a different payload within the replay window.	80 operations
`INVALID_CURSOR`	422	`starting_after` or `ending_before` is not a cursor for this list (`details.parameter`).	25 operations
`INVALID_PARAMETER`	422	A `created[gte]` or `created[lte]` bound is not a date or a timestamp with a zone (`details.parameter`).	24 operations
`INVALID_SITEMAP`	422	The URL is not a usable sitemap.	`POST /v1/crawlers`, `POST /v1/sitemap_crawlers`
`INVALID_URL`	422	The webhook URL is not a valid URL.	`POST /v1/webhook_endpoints`, `PATCH /v1/webhook_endpoints/{id}`
`MCP_DISCOVERY_FAILED`	422	The MCP server could not list its tools.	`POST /v1/actions/mcp/discover`
`ROBOTS_BLOCKED`	422	The site robots.txt disallows crawling this URL.	`POST /v1/crawlers`, `POST /v1/sitemap_crawlers`
`SAME_HOST_REJECTED`	422	The webhook URL must not point at this host.	`POST /v1/webhook_endpoints`, `PATCH /v1/webhook_endpoints/{id}`
`TEXT_EXTRACTION_FAILED`	422	No text could be extracted from the uploaded file.	`POST /v1/knowledge/{id}/replace_file`
`UNSUPPORTED_CONTENT_ENCODING`	422	The response used a content encoding the crawler does not accept.	`POST /v1/crawlers`, `POST /v1/sitemap_crawlers`
`UNSUPPORTED_CONTENT_TYPE`	422	The response content type is not one the crawler can read.	`POST /v1/crawlers`, `POST /v1/sitemap_crawlers`
`UPSTREAM_HTTP_ERROR`	422	The site responded with an HTTP error.	`POST /v1/crawlers`, `POST /v1/sitemap_crawlers`
`VALIDATION_FAILED`	422	Validation failed. `errors` and `error.details.fields` map each field to its messages.	61 operations
`WEBHOOK_ENDPOINT_LIMIT_REACHED`	422	The account already has its maximum number of webhook endpoints (`error.details.max`).	`POST /v1/webhook_endpoints`
`CRAWLER_LIMIT_REACHED`	429	Too many crawls are running at once. The crawler keeps its state.	7 operations
`RATE_LIMITED`	429	A `/v1` limiter refused the request. Wait `Retry-After` seconds.	153 operations
`SERVER_ERROR`	500	Unexpected failure. The body never carries exception text; retry with the same `Idempotency-Key`.	153 operations
`CHANNEL_UNREACHABLE`	503	The channel platform could not be reached.	`POST /v1/chatbots/{chatbotId}/channels/{platform}`
`SERVICE_UNAVAILABLE`	503	The chat turn ran out of time (`Retry-After`, and `fallback_response` when the chatbot has one).	`POST /v1/chat`

Generated from the API's own description, so every code here is one an endpoint can actually return, with the status it comes with. Each endpoint in the API reference lists the codes of each of its responses. New codes can be added over time; treat an unknown code by its HTTP status.

Which are worth retrying

The distinction that matters most in production:

Status	Retry?	Why
`429`	Yes, after `Retry-After`	Temporary by definition
`500`, `502`, `503`, `504`	Yes, with backoff	Server-side, may pass
`409 IDEMPOTENCY_IN_FLIGHT`	Yes, after a short pause	The first attempt is still running
`400`	No	A malformed header, such as `INVALID_IDEMPOTENCY_KEY`
`401`	No	Fix the key
`402`	Not until the plan or credits change	A plan limit or the credit balance refused the request
`403`	No	Fix the scopes, or the account is suspended
`404`	No	The resource does not exist on this account
`422`	No	The request is wrong and will stay wrong
`409` (other)	No	Conflicts with current state; re-read and decide

Retrying a 4xx is a loop, not a recovery

Except for 429 and the in-flight 409, a 4xx describes something about your request. Retrying it produces the same answer, forever, while consuming your rate budget.

Always send an Idempotency-Key on writes so a retry is safe — see Idempotency.

401, 403 and 404

These three get confused, and the difference is deliberate.

401 UNAUTHENTICATED — no key, a malformed key, or one that is revoked, expired, or calling from a disallowed address.
403 INSUFFICIENT_SCOPE — the key is valid but lacks the scope for this route. error.details lists required, missing and granted. The one exception is DELETE /v1/api_keys/{id} with another key's id: a key may only revoke itself, so error.details is just {"required": "self"}. A suspended account answers 403 ACCOUNT_SUSPENDED instead.
404 NOT_FOUND — either the resource does not exist, or it belongs to another account.

Why another account's resource is a 404

Answering 403 would confirm the id exists. Anyone could then discover identifiers by probing. Returning 404 means a resource you cannot reach is indistinguishable from one that was never there.

Validation failures

422 VALIDATION_FAILED is the only code that carries per-field errors:

json

{
  "error": {
    "code": "VALIDATION_FAILED",
    "details": {
      "fields": {
        "enabled_events": ["The enabled events field is required."],
        "url": ["The url must be a valid URL."]
      }
    }
  }
}

Every field error is keyed by the request field, so you can attach them directly to inputs.

Handling them

curl

# -f makes curl exit non-zero on HTTP errors; the body still prints.
curl -fsS -X POST https://api.agentency.com/v1/chatbots \
  -H "Authorization: Bearer <YOUR_KEY>" \
  -H "Content-Type: application/json" \
  -d '{}' || echo "request failed"

Server errors

A 5xx never contains a stack trace, an SQL statement, a provider response, or a file path. It carries SERVER_ERROR and a request_id.

That is deliberate — error text is one of the classic ways internals leak — but it does mean the request_id is the only handle on the incident. Log it.

What's next

Idempotency — retry without duplicating.
Rate limits — handling 429 properly.
Support — what to include in a report.

Errors

Every failure answers with the same JSON shape, whatever caused it. Switch on error.code, never on the message text — messages are localised and may be reworded; codes are part of the contract.

The envelope

json

{
  "message": "Validation failed.",
  "errors": {
    "name": ["The name field is required."]
  },
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Validation failed.",
    "details": {
      "fields": {
        "name": ["The name field is required."]
      }
    }
  },
  "request_id": "483c1c5107978d552c8f634d8b141501"
}

error.code — the machine-readable cause. This is what your code branches on.
error.details — extra context. Field errors for a 422, the required and missing scopes for a 403.
errors — the flat field map, for form libraries that expect it.
request_id — also on the X-Request-ID header. Quote it in a support request and the whole conversation gets shorter.

There is no success field on /v1. The status code already says whether it worked; a boolean that restates it is one more thing that can disagree with reality.

The codes

Code	HTTP	Description	Returned by
`ACCOUNT_SELECTOR_NOT_SUPPORTED`	400	The `X-Account-Id` header is not this key's owner, or `X-Workspace-Id` names another workspace. `details.header` names which.	151 operations
`INVALID_IDEMPOTENCY_KEY`	400	`Idempotency-Key` is present but is not 16–128 letters, digits, `_` or `-`.	80 operations
`UNAUTHENTICATED`	401	Missing, unknown, revoked, expired, rotated-out or IP-blocked API key. The reason is recorded in the request log only.	151 operations
`AGENT_LIMIT_REACHED`	402	The plan limit for agents is already reached.	`POST /v1/chatbots`
`AI_ACTION_LIMIT_REACHED`	402	The plan limit for Call Actions on this agent is already reached.	`POST /v1/actions`
`CHANNEL_LIMIT_REACHED`	402	The chatbot already has as many connected channels as the plan allows (`details.max_connected`).	`POST /v1/chatbots/{chatbotId}/channels/{platform}`
`CHATBOT_BUDGET_EXCEEDED`	402	The chatbot spent its monthly AI budget.	`POST /v1/actions/{id}/test`, `POST /v1/chat`, `POST /v1/chat/stream`
`INTEGRATIONS_NOT_AVAILABLE`	402	The plan does not include channel integrations.	`POST /v1/chatbots/{chatbotId}/channels/{platform}`
`KNOWLEDGE_PLAN_SIZE_EXCEEDED`	402	The plan limit for knowledge size is already reached.	4 operations
`MESSAGE_CREDITS_EXCEEDED`	402	The account has no message credits left this period (`details.resource`, and `details.plan` for an authenticated owner).	`POST /v1/actions/{id}/test`, `POST /v1/chat`, `POST /v1/chat/stream`
`USER_BUDGET_EXCEEDED`	402	The account spent its monthly AI budget.	`POST /v1/actions/{id}/test`, `POST /v1/chat`, `POST /v1/chat/stream`
`ACCOUNT_SUSPENDED`	403	The key owner is banned or inactive.	151 operations
`FORBIDDEN`	403	A policy refused the action, e.g. a key restricted to selected agents that holds the needed permission on none of them.	12 operations
`INSUFFICIENT_SCOPE`	403	The API key lacks a scope this operation requires.	150 operations
`ACTIONS_DISABLED`	404	Call Actions are switched off.	`POST /v1/actions/{id}/test`
`FEATURE_DISABLED`	404	This feature is switched off.	Any request, before an operation is matched
`IMPORT_PROVIDER_UNAVAILABLE`	404	That cloud import provider is not available.	`POST /v1/knowledge/import/cloud`
`MCP_NOT_ENABLED`	404	MCP actions are switched off.	`POST /v1/actions/mcp/discover`
`NOT_FOUND`	404	No resource with that id exists for this key.	117 operations
`ROUTE_NOT_FOUND`	404	The path does not match an operation.	Any request, before an operation is matched
`ACTION_TOOL_NAME_CONFLICT`	409	Could not assign a unique tool name to that action.	`POST /v1/actions`
`CHANNEL_CONNECT_BUSY`	409	Another channel connect for this chatbot is still running; nothing was written. Retry once it finishes.	`POST /v1/chatbots/{chatbotId}/channels/{platform}`
`CHATBOT_NAME_TAKEN`	409	An agent with that name already exists.	`POST /v1/chatbots`, `PATCH /v1/chatbots/{id}`
`COLLECTION_HAS_DATASETS`	409	The collection still contains knowledge sources (`details.dataset_count`).	`DELETE /v1/knowledge/collections/{id}`
`CRAWLER_INACTIVE`	409	The crawler is inactive, so this transition is refused.	5 operations
`CRAWLER_NOT_PAUSED`	409	The crawler is not paused, so this transition is refused.	`POST /v1/crawlers/{id}/resume`, `POST /v1/sitemap_crawlers/{id}/resume`
`CRAWLER_NOT_RUNNING`	409	The crawler is not running, so this transition is refused.	`POST /v1/crawlers/{id}/pause`, `POST /v1/sitemap_crawlers/{id}/pause`
`CRAWLER_RUNNING`	409	The crawler is already running, so this transition is refused.	5 operations
`CRAWLER_TERMINAL`	409	The crawler has finished, so this transition is refused.	`POST /v1/crawlers/queue/cancel`, `POST /v1/crawlers/{id}/cancel`
`CRAWL_NOT_RETRYABLE`	409	This crawl cannot be retried.	`POST /v1/crawlers/{id}/retry`, `POST /v1/sitemap_crawlers/{id}/scan`, `POST /v1/sitemap_crawlers/{id}/retry`
`DATASET_DELETING`	409	The knowledge source is being removed.	8 operations
`DATASET_NOT_UPLOAD_SOURCED`	409	Replacing a file only applies to an uploaded knowledge source.	`POST /v1/knowledge/{id}/replace_file`
`DATASET_NOT_URL_SOURCED`	409	Recrawl only applies to a URL, link or sitemap source.	`POST /v1/knowledge/{id}/recrawl`
`DELIVERY_ALREADY_DELIVERED`	409	The delivery already succeeded. Only a failed delivery can be retried.	`POST /v1/webhook_deliveries/{id}/retry`
`DELIVERY_IN_FLIGHT`	409	A retry is already in progress for this delivery.	`POST /v1/webhook_deliveries/{id}/retry`
`ENDPOINT_URL_ALREADY_REGISTERED`	409	A webhook endpoint with that URL already exists.	`POST /v1/webhook_endpoints`, `PATCH /v1/webhook_endpoints/{id}`
`FILE_BACKS_DATASET`	409	The file still backs a knowledge source (`details.dataset_id`). Remove that source first.	`DELETE /v1/files/{id}`
`IDEMPOTENCY_IN_FLIGHT`	409	A request with the same `Idempotency-Key` is still running. Retry after `Retry-After` seconds.	80 operations
`INGESTION_IN_PROGRESS`	409	Knowledge processing is already running.	`PATCH /v1/knowledge/{id}`, `POST /v1/knowledge/{id}/retry`, `POST /v1/knowledge/{id}/replace_file`
`KNOWLEDGE_NAME_TAKEN`	409	A knowledge source with that name already exists.	`POST /v1/knowledge`, `PATCH /v1/knowledge/{id}`, `POST /v1/knowledge/import/cloud`
`NOTHING_TO_CANCEL`	409	There is no ingest in progress to cancel.	`POST /v1/knowledge/{id}/cancel`
`RECRAWL_IN_PROGRESS`	409	A recrawl is already running.	`POST /v1/knowledge/{id}/recrawl`
`ACTION_LIMIT_REACHED`	422	This agent already has the maximum number of enabled actions.	`POST /v1/actions`, `PATCH /v1/actions/{id}`
`ACTION_TYPE_UNAVAILABLE`	422	That action type is not available.	`POST /v1/actions`
`BLOCKED_DESTINATION`	422	The URL points at a blocked destination.	`POST /v1/webhook_endpoints`, `PATCH /v1/webhook_endpoints/{id}`
`BLOCKED_DOMAIN`	422	The URL host is blocked or not routable.	`POST /v1/crawlers`, `POST /v1/sitemap_crawlers`
`CHALLENGE_BLOCKED`	422	The site answered with a human-verification page instead of the document.	`POST /v1/crawlers`, `POST /v1/sitemap_crawlers`
`CHANNEL_CONNECTION_FAILED`	422	The channel platform rejected the credentials.	`POST /v1/chatbots/{chatbotId}/channels/{platform}`
`CHATBOT_REQUIRED`	422	This knowledge source needs an agent.	`POST /v1/knowledge`, `POST /v1/knowledge/{id}/retry`
`CLOUD_IMPORT_FAILED`	422	None of the picked cloud files could be imported (`error.details.failures`).	`POST /v1/knowledge/import/cloud`
`COLLECTION_NOT_OWNED_BY_CHATBOT`	422	The collection belongs to a different agent than `chatbot_id`.	`POST /v1/knowledge`, `POST /v1/knowledge/import/cloud`, `POST /v1/knowledge/collections/{id}/datasets`
`CONTENT_TOO_LARGE`	422	The document is larger than the crawl size cap.	`POST /v1/crawlers`, `POST /v1/sitemap_crawlers`
`CORRUPT_CONTENT_ENCODING`	422	The response body could not be decoded.	`POST /v1/crawlers`, `POST /v1/sitemap_crawlers`
`CRAWLING_ERROR`	422	The crawl could not start.	`POST /v1/crawlers`, `POST /v1/sitemap_crawlers`
`EXPORT_TOO_LARGE`	422	The filtered export is over the row cap (`details.limit`, `details.rows`, `details.max_rows`). Narrow the filters.	`GET /v1/customers/export`
`HTTPS_REQUIRED`	422	The webhook URL must use HTTPS.	`POST /v1/webhook_endpoints`, `PATCH /v1/webhook_endpoints/{id}`
`IDEMPOTENCY_KEY_REUSED`	422	The `Idempotency-Key` was already used with a different payload within the replay window.	80 operations
`INVALID_CURSOR`	422	`starting_after` or `ending_before` is not a cursor for this list (`details.parameter`).	25 operations
`INVALID_PARAMETER`	422	A `created[gte]` or `created[lte]` bound is not a date or a timestamp with a zone (`details.parameter`).	24 operations
`INVALID_SITEMAP`	422	The URL is not a usable sitemap.	`POST /v1/crawlers`, `POST /v1/sitemap_crawlers`
`INVALID_URL`	422	The webhook URL is not a valid URL.	`POST /v1/webhook_endpoints`, `PATCH /v1/webhook_endpoints/{id}`
`MCP_DISCOVERY_FAILED`	422	The MCP server could not list its tools.	`POST /v1/actions/mcp/discover`
`ROBOTS_BLOCKED`	422	The site robots.txt disallows crawling this URL.	`POST /v1/crawlers`, `POST /v1/sitemap_crawlers`
`SAME_HOST_REJECTED`	422	The webhook URL must not point at this host.	`POST /v1/webhook_endpoints`, `PATCH /v1/webhook_endpoints/{id}`
`TEXT_EXTRACTION_FAILED`	422	No text could be extracted from the uploaded file.	`POST /v1/knowledge/{id}/replace_file`
`UNSUPPORTED_CONTENT_ENCODING`	422	The response used a content encoding the crawler does not accept.	`POST /v1/crawlers`, `POST /v1/sitemap_crawlers`
`UNSUPPORTED_CONTENT_TYPE`	422	The response content type is not one the crawler can read.	`POST /v1/crawlers`, `POST /v1/sitemap_crawlers`
`UPSTREAM_HTTP_ERROR`	422	The site responded with an HTTP error.	`POST /v1/crawlers`, `POST /v1/sitemap_crawlers`
`VALIDATION_FAILED`	422	Validation failed. `errors` and `error.details.fields` map each field to its messages.	61 operations
`WEBHOOK_ENDPOINT_LIMIT_REACHED`	422	The account already has its maximum number of webhook endpoints (`error.details.max`).	`POST /v1/webhook_endpoints`
`CRAWLER_LIMIT_REACHED`	429	Too many crawls are running at once. The crawler keeps its state.	7 operations
`RATE_LIMITED`	429	A `/v1` limiter refused the request. Wait `Retry-After` seconds.	153 operations
`SERVER_ERROR`	500	Unexpected failure. The body never carries exception text; retry with the same `Idempotency-Key`.	153 operations
`CHANNEL_UNREACHABLE`	503	The channel platform could not be reached.	`POST /v1/chatbots/{chatbotId}/channels/{platform}`
`SERVICE_UNAVAILABLE`	503	The chat turn ran out of time (`Retry-After`, and `fallback_response` when the chatbot has one).	`POST /v1/chat`

Which are worth retrying

The distinction that matters most in production:

Status	Retry?	Why
`429`	Yes, after `Retry-After`	Temporary by definition
`500`, `502`, `503`, `504`	Yes, with backoff	Server-side, may pass
`409 IDEMPOTENCY_IN_FLIGHT`	Yes, after a short pause	The first attempt is still running
`400`	No	A malformed header, such as `INVALID_IDEMPOTENCY_KEY`
`401`	No	Fix the key
`402`	Not until the plan or credits change	A plan limit or the credit balance refused the request
`403`	No	Fix the scopes, or the account is suspended
`404`	No	The resource does not exist on this account
`422`	No	The request is wrong and will stay wrong
`409` (other)	No	Conflicts with current state; re-read and decide

Retrying a 4xx is a loop, not a recovery

Except for 429 and the in-flight 409, a 4xx describes something about your request. Retrying it produces the same answer, forever, while consuming your rate budget.

Always send an Idempotency-Key on writes so a retry is safe — see Idempotency.

401, 403 and 404

These three get confused, and the difference is deliberate.

401 UNAUTHENTICATED — no key, a malformed key, or one that is revoked, expired, or calling from a disallowed address.
403 INSUFFICIENT_SCOPE — the key is valid but lacks the scope for this route. error.details lists required, missing and granted. The one exception is DELETE /v1/api_keys/{id} with another key's id: a key may only revoke itself, so error.details is just {"required": "self"}. A suspended account answers 403 ACCOUNT_SUSPENDED instead.
404 NOT_FOUND — either the resource does not exist, or it belongs to another account.

Why another account's resource is a 404

Answering 403 would confirm the id exists. Anyone could then discover identifiers by probing. Returning 404 means a resource you cannot reach is indistinguishable from one that was never there.

Validation failures

422 VALIDATION_FAILED is the only code that carries per-field errors:

json

{
  "error": {
    "code": "VALIDATION_FAILED",
    "details": {
      "fields": {
        "enabled_events": ["The enabled events field is required."],
        "url": ["The url must be a valid URL."]
      }
    }
  }
}

Every field error is keyed by the request field, so you can attach them directly to inputs.

Handling them

curl

# -f makes curl exit non-zero on HTTP errors; the body still prints.
curl -fsS -X POST https://api.agentency.com/v1/chatbots \
  -H "Authorization: Bearer <YOUR_KEY>" \
  -H "Content-Type: application/json" \
  -d '{}' || echo "request failed"

Server errors

A 5xx never contains a stack trace, an SQL statement, a provider response, or a file path. It carries SERVER_ERROR and a request_id.

That is deliberate — error text is one of the classic ways internals leak — but it does mean the request_id is the only handle on the incident. Log it.

What's next

Idempotency — retry without duplicating.
Rate limits — handling 429 properly.
Support — what to include in a report.