Errors

Every response is an envelope. Successes carry data. Failures carry a stable code you can branch on.

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"
  }
}

status · string · required

Always error on failure.

error.message · string · required

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

error.code · string · required

Stable machine-readable code. Branch on this.

error.details · 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.