Errors and limits
The error format, what each HTTP status means and whether to retry, validation details, common error codes, and the size and rate limits of the API.
Error format
Every error is a JSON object with a human-readable error. Many also carry a machine-readable code you can branch on.
{
"error": "X-Veyra-Run-Id does not match signed agent JWT run_id",
"code": "agent_jwt_run_id_mismatch"
}Validation errors list every problem with the field it belongs to:
{
"error": "Validation error",
"details": [
{ "code": "too_big", "maximum": 255, "path": ["idempotencyKey"], "message": "Too big: expected string to have <=255 characters" }
]
}A body that is not valid JSON returns 400 with {"error": "Invalid JSON body"} and nothing from your request.
Status codes
| Status | Meaning | Retry? |
|---|---|---|
200 201 202 204 |
Success. 202 means the work continues in the background. |
— |
400 |
Malformed or invalid request. Read details. |
No |
401 |
Missing, unknown, revoked or expired key; or the agent cannot authenticate. | No |
403 |
The key may not do this (organization, permission, or key type). | No |
404 |
Not found among what this key can see. Also returned for things that exist but are hidden from you. | No |
409 |
Conflict with the current state: already checked out, already answered, archived, changed meanwhile. | No; re-read and decide |
413 |
Body or file too large. | No |
415 |
Wrong content type. | No |
422 |
The request is valid but a rule forbids it now. | No |
429 |
Too many requests. Wait Retry-After seconds. |
Yes |
500 |
Server error. | Yes, with backoff |
503 |
A dependency is unavailable or the server is restarting. | Yes, with backoff |
Note
404 instead of 403 is deliberate for resources in other organizations or in private tasks and folders: the API does not reveal that they exist.
Common error codes
| Code | Status | What happened |
|---|---|---|
agent_jwt_run_id_mismatch |
422 | X-Veyra-Run-Id does not match the run token. |
agent_run_cancelled |
403 | The run was cancelled; its token can no longer change anything. |
agent_run_superseded |
403 | A newer run continues this task; end the turn. |
conversation_turn_cancelled |
403 | The chat turn was cancelled. |
run_id_required |
400 | The endpoint needs the run id of the calling agent run. |
skill_policy_denied |
403 | Organization skill policy does not allow this skill. |
delegation_cycle |
422 | The assignment would make a task wait on itself through others. |
rate_limited |
429 | Too many requests for this resource. |
Endpoints with their own codes list them on their reference page or in their error message.
Limits
| Limit | Value |
|---|---|
| JSON body | 10 MB |
| Uploaded file | 10 MB |
Routine webhook Idempotency-Key / idempotencyKey |
255 characters |
| Webhook replay window (signed routine triggers) | 30 seconds to 24 hours; 300 seconds by default |
| Chat provider webhooks | 600 requests per minute per endpoint and source address |
| Voice callbacks | 600 requests per minute per source address |
Rate limits
Requests pass through Cloudflare, which protects the API against floods. Individual endpoints that are easy to abuse, such as invitations and webhook ingress, have their own limits and answer 429 with Retry-After and X-RateLimit-Limit / X-RateLimit-Remaining headers.
Build clients that:
- Respect
Retry-Afteron429. - Back off exponentially on
5xxand network errors, with jitter. - Use idempotency keys so retries never duplicate work.
- Keep a few requests in flight at a time rather than hundreds.