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.

Veyra Docs TeamUpdated 2 min readVersion 3 · History

Error format

Every error is a JSON object with a human-readable error. Many also carry a machine-readable code you can branch on.

JSON
{
  "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:

JSON
{
  "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-After on 429.
  • Back off exponentially on 5xx and network errors, with jitter.
  • Use idempotency keys so retries never duplicate work.
  • Keep a few requests in flight at a time rather than hundreds.
APIDevelopersErrorsRate limits