Errors - Rook API | Rook Developer Portal

Failures use the matching HTTP status and a uniform JSON envelope. Every response, including errors, includes X-Request-ID. On failures that value matches error.request_id.

json

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_request",
    "message": "invalid order by: foo. Valid options are: [created_at updated_at]",
    "param": "order_by",
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "doc_url": "https://docs.rookpayments.com/errors/invalid_request"
  }
}

Branch on HTTP status and error.code. Do not parse error.message as a stable contract. param names the JSON field, query parameter, or header that failed, or is null.

Catalogue

HTTP	`type`	`code`	When
400	`invalid_request_error`	`invalid_request`	Malformed JSON, failed schema validation, or conflicting query parameters.
400	`invalid_request_error`	`program_required`	`X-Program-ID` omitted while the API key can access more than one program.
401	`authentication_error`	`authentication_error`	Missing or invalid API key.
403	`permission_error`	`permission_denied`	The key cannot access this program or resource.
404	`not_found_error`	`not_found`	Unknown id, or the resource is not visible to this key.
409	`conflict_error`	`conflict`	Incompatible state transition.
409	`conflict_error`	`idempotency_conflict`	`Idempotency-Key` reused with a different body, or a matching request is in flight.
422	`invalid_request_error`	`insufficient_funds`	The source financial account does not have enough available balance.
422	`invalid_request_error`	`card_not_active`	The card is not in a state that can authorize or capture.
422	`invalid_request_error`	`card_expired`	The card's expiration date has passed.
422	`invalid_request_error`	`wallet_closed`	The financial account or wallet entity is closed.
422	`invalid_request_error`	`limit_exceeded`	The request would exceed a spend, velocity, or balance limit.
429	`rate_limit_error`	`rate_limited`	The key exceeded its rate limit. Honor `Retry-After`.
500	`api_error`	`internal_error`	Unexpected failure. Retry with the same `Idempotency-Key`.

doc_url is https://docs.rookpayments.com/errors/{code}.

Rate limits

Limits are enforced per API key. Burst and sustained ceilings can differ between sandbox and production. When a limit is exceeded the API returns 429 with:

Retry-After: integer seconds to wait before retrying
error.code of rate_limited

Back off exponentially and cap parallel callers per key. Prefer webhooks over tight polling. Idempotent retries after a 429 are safe when Idempotency-Key is set.