Errors - Katalo API

The API uses standard HTTP status codes and returns a normalized JSON error envelope for failures.

Error envelope

{
  "error": {
    "code": "validation_error",
    "message": "Request fields failed validation.",
    "retryable": false,
    "retry_after": null
  }
}

HTTP status codes

Status	Code	Meaning	Retry?
`400`	`bad_request`	Malformed JSON, invalid multipart, or mutually exclusive source inputs.	No
`401`	`unauthorized`	Missing or malformed bearer token.	No
`403`	`forbidden`	API access is disabled or the key does not belong to an approved organization.	No
`404`	`not_found`	The requested job, source asset, or page does not exist for the caller.	No
`409`	`idempotency_conflict`	The same `Idempotency-Key` was reused with a different payload.	No
`422`	`validation_error`	Request fields fail the workflow and capture-type validation matrix.	No
`429`	`rate_limited`	Per-key, per-org, or per-IP limit exceeded.	Yes
`500`	`internal_error`	Unexpected server-side failure.	Yes

Handling failures

Treat authentication and validation failures as terminal until the request or access model is fixed.
Retry 429 only after the advertised retry window.
Retry retryable 5xx failures with backoff.
Keep the same idempotency key when retrying the same write request.