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.
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
| Code | HTTP | Meaning and what to do |
|---|---|---|
invalid_api_key | 401 | The key is missing, unknown, expired or revoked. Check the Authorization header or create a new key. |
api_not_enabled | 403 | The API is not switched on for this workspace yet. |
insufficient_scope | 403 | The integration lacks the permission named in the message. Add it in API & Integrations. |
read_only_integration | 403 | The integration has read-only access; this call changes something. |
access_denied | 403 | The integration or its workspace is no longer valid for this call. |
plan_restricted | 403 | The 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_reached | 403 | The plan's knowledge source limit is reached. |
not_found | 404 | The resource does not exist or belongs to another workspace, integration or agent. |
method_not_allowed | 405 | This path does not support the HTTP method. |
invalid_argument | 400 | A value is invalid; the message names it. |
invalid_cursor | 400 | Pass next_cursor of the previous page as after. |
invalid_idempotency_key | 400 | Idempotency-Key must be 1 to 255 printable characters. |
context_too_large | 400 | context is limited to 8000 characters. |
context_not_allowed_in_group | 400 | context was sent to a group conversation. Everyone in a group reads the answer; send the message without context. |
content_too_large | 400 | A single record is too large to return; read it in parts. |
invalid_webhook | 400 | The webhook address is not a public https address, or an event type is unknown. |
validation_error | 422 | The body or a parameter does not match the schema; errors lists each field and reason. |
credits_exhausted | 402 | The agent's AI credits are used up. Nothing was stored or charged. Add credits or upgrade. |
usage_limit_reached | 402 | The agent's monthly answer allowance is used up. |
idempotency_conflict | 409 | This Idempotency-Key was used with a different request. Use a new key. |
request_in_progress | 409 | A request with this Idempotency-Key is still running. Retry after Retry-After. |
version_conflict | 409 | The resource changed since you read it. Read it again and decide before retrying. |
retryable_conflict | 409 | A concurrent change interrupted the call. Retry the identical request with the same key. |
conversation_agent_mismatch | 409 | The conversation belongs to a different agent. |
conversation_mismatch | 409 | conversation_id and external_id name different conversations. |
conversation_deleted | 409 | The conversation was deleted while its answer was produced. Nothing of the request was kept. |
operation_in_progress | 409 | Another operation on this agent is running (for example its deletion). |
endpoint_limit | 409 | An integration can have at most 10 webhooks. |
endpoint_disabled | 409 | Resume the webhook before sending a test. |
rate_limit_exceeded | 429 | Too many requests in this minute. Wait for Retry-After. |
concurrency_limit_exceeded | 429 | Too many answers running at once in this workspace. Retry after Retry-After or use async. |
queue_limit_exceeded | 429 | The workspace already has 100 async requests waiting. Retry after Retry-After. |
too_many_failed_attempts | 429 | Too many requests with a missing or invalid key from your address in this minute. Fix the key and wait for Retry-After. |
api_capacity_exhausted | 503 | The API as a whole is at capacity. Retry after Retry-After or use async. |
generation_failed | 500 | The answer could not be generated. The response is stored as failed; retry with a new key. |
generation_timeout | 504 | The agent did not finish within 120 seconds. Use a stream or async for long tasks. |
expired | 500 | An 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. |
interrupted | 500 | The request was interrupted by a restart and was not run again. Send it again if needed. |
integration_revoked | 500 | The integration was revoked before its async request ran. It appears as error.code of the response. |
feature_unavailable | 503 | This part of the platform is temporarily switched off. |
worker_unavailable | 503 | The import worker is not available; nothing was queued. Retry later. |
upload_unavailable | 503 | File uploads are not available right now. Retry later. |
internal_error | 500 | Something went wrong on our side. Retry, or contact support with the request id. |