Errors

Response shape

The self-host engine returns a single-field error object:

{ "error": "Human-readable message" }

The hosted API returns a structured envelope:

{
  "status": "error",
  "statusCode": 400,
  "message": "Human-readable error message",
  "errors": []
}

The Python SDK normalizes both - AgentXEvaluationsError and friends carry the message either way, so application code never needs to branch on the shape.

Status codes

Code	When it occurs	Retry?
`400`	Missing/invalid field, batch too large, invalid parameter	No - fix the request
`401`	Missing or invalid API key; no session in `AGENTX_AUTH=enabled` mode	No - fix credentials
`403`	Authenticated but not allowed (wrong organization, mode-gated route)	No
`404`	Resource doesn’t exist or belongs to another project	No
`409`	Run already finalized/failed; analysis already running	No - check state first
`429`	Rate limited (hosted only)	Yes, with backoff
`500`	Unexpected server error	Yes, with backoff

Common cases

401 on every request (self-host) - the key is wrong or absent. Copy the Default project API key: agtx_local_... line from the engine’s startup log; the dashboard prompts for it on the connect screen, SDK/CI callers set AGENTX_API_KEY. In AGENTX_AUTH=enabled mode, dashboard routes want a signed-in session instead - see Authentication. 409 from POST /results - the run is already in a terminal state (completed or failed). Check GET /runs/:id before submitting more batches; a finalize that already happened can’t be reopened. 400 "Batch size must not exceed 10" - result submission is capped at 10 per batch. The SDK’s execute() batches for you; hand-rolled callers should chunk.

Retrying

Safe on 500 and 429, with exponential backoff.
Not safe on result submission without idempotency: always send idempotencyKey on each result (the SDK does this automatically), so a retried batch never scores the same case twice.
Trace ingest is idempotent when a span_id is supplied - replaying the same span updates nothing and triggers no duplicate judging. Importers (agentx-moveworks, agentx-databricks) rely on exactly this.

Get Started

Self-Hosting

Python SDK

Response shape

Status codes

Common cases

Retrying

​Response shape

​Status codes

​Common cases

​Retrying

Response shape

Status codes

Common cases

Retrying