Errors

A successful response has status: "success" and a data object. A failure has status: "error" and an error object.

{
  "status": "error",
  "error": {
    "message": "Unsupported rail 'foo'",
    "code": "UNSUPPORTED_RAIL"
  }
}

string

required

Always error on failure.

string

required

Human-readable explanation. Safe to show a developer; do not parse it.

string

required

Stable machine-readable code. Branch on this.

array

Optional extra context — validation messages, and so on.

HTTP status codes

Status	Meaning
`200`	Success.
`201`	Created (a thread).
`202`	Accepted (a run or an outcome).
`400`	Bad request — missing or illegal parameters.
`401`	Missing or invalid credential.
`402`	Workspace is out of credits.
`403`	Authenticated, but not allowed (realtime channel, unverified email).
`404`	The referenced resource does not exist.
`409`	Conflict.
`422`	The request was understood but cannot be processed.
`429`	Rate limited.
`500`	Something broke on our side.

Error codes

Code	Status	When
`MISSING_PARAMETER`	`400`	A required field was omitted (`rail`, `code`, …).
`UNSUPPORTED_RAIL`	`400`	`rail` is not one Identify supports.
`INVALID_CODE`	`400`	The identifier failed validation (malformed NUBAN, bad IBAN check digits, …).
`UNAUTHORIZED`	`401`	Missing or invalid API key or session token.
`INSUFFICIENT_CREDITS`	`402`	Identify — workspace balance is empty.
`insufficient_credits`	`402`	Loom — workspace balance is empty.
`FORBIDDEN`	`403`	Not allowed on this resource.
`NOT_FOUND`	`404`	Unknown thread, run, agent, or action.
`unknown_action`	`404`	Outcome posted for a tool call that is not a pending proposed action.
`VALIDATION_ERROR`	`422`	A field was present but failed model validation.
`not_awaiting_outcome`	`422`	Outcome posted against a run that is not waiting.
`invalid_state`	`422`	Outcome `state` is not `occurred` or `failed`.
`connection_required`	`422`	The agent has unpinned customer tools and no connection was named.
`RATE_LIMITED`	`429`	Burst or sustained limit hit. Honor `Retry-After`.
`INTERNAL_SERVER_ERROR`	`500`	Unexpected failure.

Loom connection errors (unknown_connection, connection_locked, connection_mismatch) are 400 or 422 depending on the path. The message explains which.

Identify codes are SCREAMING_SNAKE. A few Loom codes are snake_case. Match the string exactly.

Core

Identify

Loom

Coming soon

Identify

Loom

HTTP status codes

Error codes

​HTTP status codes

​Error codes

HTTP status codes

Error codes