Skip to main content

Errors

Every failed request returns the standard error envelope:

{
  "success": false,
  "error": {
    "code": "STRING_CODE",
    "message": "Human-readable description"
  }
}

Error codes​

CodeHTTP statusWhen it happensHow to handle it
VALIDATION_ERROR422The request body failed schema validation (missing or malformed fields).Fix the request — check the field table on the endpoint you called. Not retryable as-is.
NOT_FOUND404The session, action, escalation, or project referenced doesn't exist, or doesn't belong to your project.Fatal for that id — don't retry with the same id. See the note on 404 vs. 403 below.
ESCALATION_RESOLVED409You tried to send a message into an escalation that's already resolved.Fatal for that escalation — start a new one with POST /agent/escalation if the user needs help again.
RECOVER_PENDING_FAILED500Internal error fetching pending actions on GET /agent/session/:sessionId/pending-actions.Transient — safe to retry with backoff.
UNSUPPORTED_MODEL422The project's configured AI model isn't supported for this operation. Can occur on /agent/message, /agent/message/stream, and /agent/continue.Not retryable — check your project's model configuration in the dashboard.
AI_RELAY_ERROR502The upstream AI call failed.Transient — safe to retry.

Generic HTTP semantics​

  • 401 — missing, malformed, invalid, or expired API key. See Authentication.
  • 404 vs. 403 — the API deliberately returns 404 NOT_FOUND rather than 403 Forbidden when a request references an id that exists but belongs to a different project. This is intentional: it avoids confirming to a caller that an id exists at all outside their own project.

Retry guidance​

SituationRetry?
AI_RELAY_ERROR, RECOVER_PENDING_FAILED, or a network-level failureYes, with backoff.
VALIDATION_ERROR, UNSUPPORTED_MODEL, NOT_FOUND, ESCALATION_RESOLVEDNo — fix the request or the referenced id first.
401No — refresh or check your API key before retrying.
Connection error on POST /agent/message/stream before any SSE event arrivesYes — retry via the non-streaming POST /agent/message (see Messages & streaming).
Last updated on