Error Codes
Error codes returned by the Elizon Public API.
Every error response is JSON. Most follow { "error": "<code>", "message": "<human-readable>" }; validation failures use { "errors": [{ "path", "message" }] } instead — see the table below for which shape applies where.
| HTTP status | error | When it occurs | Suggested action |
|---|---|---|---|
400 | validation error ({ "errors": [...] }) | Request body or query params fail schema validation (missing required field, wrong type, out-of-range value) | Fix the field(s) named in errors[].path; each entry's message explains what failed. |
400 | invalid_tool_context | tool_context was provided but isn't valid JSON | Send a JSON-encoded string, or omit the field. |
401 | unauthorized | X-API-Key header missing, malformed, invalid, expired, or revoked | Check the header is present and correctly formatted (see Authentication). Elizon doesn't distinguish these cases in the response — if a previously working key suddenly fails, check whether it was revoked or has an expiresAt in the past. |
403 | forbidden | A project-scoped key tried to access an agent or job that exists but belongs to a different project | Use the correct project-scoped key, or an org-scoped key. |
404 | agent_not_found | No agent with that ID exists in your organization | Check the agentId — this is also returned (not 403) for agents in another organization entirely. |
404 | job_not_found | No job with that ID exists for your organization/project | Check the jobId. Also returned for jobs belonging to another tenant — never 403 — so a job ID alone never confirms another tenant's job exists. |
404 | run_not_found | Cancelling a run (DELETE .../runs/:runId) with an unknown runId | Check the runId returned by /run or the RunStarted streaming event. |
422 | project_not_found | project_ref_id / projectId doesn't belong to your organization | Use a project ID that exists in your org, or omit it. |
422 | llm_configuration_not_found | config references an llm_config_id that doesn't exist or isn't connected | Call GET /agents/llm-providers to list valid, connected configurations. |
429 | rate_limit_exceeded | Organization or per-key rate limit exceeded | Back off for retry_after seconds (see Rate Limiting). |
502 | bad_gateway / upstream_error / enqueue_failed | The agent runtime is unreachable, errored mid-run, or a job couldn't be queued | Transient — safe to retry with backoff. |
504 | execution_timeout | A synchronous /run call didn't finish within 30 seconds | Switch that call to /run-async and poll for the result. |