Errors

Every error returns a consistent JSON shape under an error key:

{
  "error": {
    "type": "unbalanced_journal",
    "message": "Debits (25000000) do not equal credits (24000000).",
    "code": "journal.unbalanced",
    "param": "entries"
  }
}

type — a stable, machine-readable category. Branch on this.
message — a human-readable explanation. Safe to log; do not pattern-match on it.
code — a dotted sub-code for finer handling.
param — the offending field, when applicable.

Status codes

Status	Meaning	What to do
`400`	Malformed request	Fix the request shape.
`401`	Missing/invalid API key	Check the `Authorization` header.
`402`	Insufficient AI credits	Top up credits (categorization).
`404`	Resource not found	Check the ID and that it belongs to you.
`409`	Conflict (e.g. duplicate)	Safe to treat as already-done with idempotency.
`422`	Unprocessable (e.g. unbalanced journal)	Fix the business-rule violation.
`429`	Rate limited	Back off and retry with jitter.
`5xx`	Server error	Retry with backoff; the request may not have applied — reuse your idempotency key.

Pair 429 and 5xx handling with idempotency keys so retries never double-post.

Get started

Core concepts

Guides

Status codes

​Status codes

Status codes