Errors - Kualia

Every error response has a non-2xx status code and a consistent body:

{
  "error": {
    "id": "404",
    "name": "not_found",
    "detail": "Transaction not found"
  }
}

id mirrors the HTTP status, name is a stable machine-readable code, and detail is a human-readable explanation (its wording may change — branch on name, not detail).

Error codes

Status	`name`	When
400	`bad_request`	Invalid JSON, missing/invalid fields, malformed amounts or dates, invalid cursor
401	`unauthorized`	Missing, invalid, or revoked API key
403	`forbidden`	Read-only key on a write endpoint, no access to the workspace, or workspace archived
404	`not_found`	Unknown endpoint, or the workspace/account/transaction/merchant/category doesn’t exist
409	`conflict`	Duplicate name (e.g. merchant or category group already exists)
429	`rate_limit_exceeded`	More than 200 requests in an hour for this key
500	`internal_error`	Something went wrong on our side — retry with backoff, and contact support if it persists

Rate limiting

Each API key may make 200 requests per hour. When you exceed it, the response is 429 with a Retry-After header containing the number of seconds until the window resets:

HTTP/1.1 429 Too Many Requests
Retry-After: 1284

{ "error": { "id": "429", "name": "rate_limit_exceeded", "detail": "Rate limit exceeded. The limit is 200 requests per hour per API key." } }

Batch endpoints help you stay under the limit — for example, POST /transactions accepts up to 100 transactions in one request.

Validation errors reference fields by path

Field errors name the offending field, including array indices, so you can pinpoint the bad row in a batch:

{
  "error": {
    "id": "400",
    "name": "bad_request",
    "detail": "transactions[2].amount must be a decimal string in the workspace currency (e.g. \"-12.34\")"
  }
}