API errors

Every error of the API has the same form, whatever went wrong: an HTTP status and a JSON body with type, code, message, request_id and doc_url, which links to the code below.

1 min read Updated

Format

HTTP

HTTP/1.1 429 Too Many Requests
Retry-After: 2
X-Request-Id: req_4f1c2a9e7b3d5f6a8c0e1b2d

{
  "error": {
    "type": "rate_limit_error",
    "code": "concurrency_limit_exceeded",
    "message": "This workspace already runs 5 answers at once. Retry shortly or use \"async\": true.",
    "request_id": "req_4f1c2a9e7b3d5f6a8c0e1b2d",
    "doc_url": "https://docs.ultimo-bots.com/api/errors#concurrency_limit_exceeded"
  }
}

Codes

CodeHTTPMeaning and what to do
invalid_api_key401The key is missing, unknown, expired or revoked. Check the Authorization header or create a new key.
api_not_enabled403The API is not switched on for this workspace yet.
insufficient_scope403The integration lacks the permission named in the message. Add it in API & Integrations.
read_only_integration403The integration has read-only access; this call changes something.
access_denied403The integration or its workspace is no longer valid for this call.
plan_restricted403The agent's plan does not include the API, or the requested feature (for example removing the branding). The agent object shows this as api_access: false.
plan_limit_reached403The plan's knowledge source limit is reached.
not_found404The resource does not exist or belongs to another workspace, integration or agent.
method_not_allowed405This path does not support the HTTP method.
invalid_argument400A value is invalid; the message names it.
invalid_cursor400Pass next_cursor of the previous page as after.
invalid_idempotency_key400Idempotency-Key must be 1 to 255 printable characters.
context_too_large400context is limited to 8000 characters.
context_not_allowed_in_group400context was sent to a group conversation. Everyone in a group reads the answer; send the message without context.
content_too_large400A single record is too large to return; read it in parts.
invalid_webhook400The webhook address is not a public https address, or an event type is unknown.
validation_error422The body or a parameter does not match the schema; errors lists each field and reason.
credits_exhausted402The agent's AI credits are used up. Nothing was stored or charged. Add credits or upgrade.
usage_limit_reached402The agent's monthly answer allowance is used up.
idempotency_conflict409This Idempotency-Key was used with a different request. Use a new key.
request_in_progress409A request with this Idempotency-Key is still running. Retry after Retry-After.
version_conflict409The resource changed since you read it. Read it again and decide before retrying.
retryable_conflict409A concurrent change interrupted the call. Retry the identical request with the same key.
conversation_agent_mismatch409The conversation belongs to a different agent.
conversation_mismatch409conversation_id and external_id name different conversations.
conversation_deleted409The conversation was deleted while its answer was produced. Nothing of the request was kept.
operation_in_progress409Another operation on this agent is running (for example its deletion).
endpoint_limit409An integration can have at most 10 webhooks.
endpoint_disabled409Resume the webhook before sending a test.
rate_limit_exceeded429Too many requests in this minute. Wait for Retry-After.
concurrency_limit_exceeded429Too many answers running at once in this workspace. Retry after Retry-After or use async.
queue_limit_exceeded429The workspace already has 100 async requests waiting. Retry after Retry-After.
too_many_failed_attempts429Too many requests with a missing or invalid key from your address in this minute. Fix the key and wait for Retry-After.
api_capacity_exhausted503The API as a whole is at capacity. Retry after Retry-After or use async.
generation_failed500The answer could not be generated. The response is stored as failed; retry with a new key.
generation_timeout504The agent did not finish within 120 seconds. Use a stream or async for long tasks.
expired500An async request waited 15 minutes without being started and was not run. Send it again if you still need the answer. It appears as error.code of the response, not as an HTTP status.
interrupted500The request was interrupted by a restart and was not run again. Send it again if needed.
integration_revoked500The integration was revoked before its async request ran. It appears as error.code of the response.
feature_unavailable503This part of the platform is temporarily switched off.
worker_unavailable503The import worker is not available; nothing was queued. Retry later.
upload_unavailable503File uploads are not available right now. Retry later.
internal_error500Something went wrong on our side. Retry, or contact support with the request id.

Next steps