Error Handling & Rate Limits

Failures in the Rook API use standard HTTP status codes and a deterministic, uniform JSON error envelope. Every response includes a unique X-Request-ID header for end-to-end tracing.

Standard Error Envelope

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

Always branch programmatically on HTTP status and error.code. Do not parse error.message as a stable contract. The param field indicates the specific field, query parameter, or header that failed validation.

Error Code Catalogue

HTTP	Type	Code	Trigger Condition
400	invalid_request_error	invalid_request	Malformed JSON, schema violation, or invalid parameters.
400	invalid_request_error	program_required	`X-Program-ID` omitted when the key has access to multiple programs.
401	authentication_error	authentication_error	Missing, malformed, or expired API key / Bearer token.
403	permission_error	permission_denied	Key lacks permission for this operation or program tenant partition.
404	not_found_error	not_found	Unknown resource ID or entity belongs to another tenant.
409	conflict_error	conflict	Incompatible resource state transition.
409	conflict_error	idempotency_conflict	`Idempotency-Key` reused with a mismatched request payload.
422	invalid_request_error	insufficient_funds	Source financial wallet lacks sufficient available balance.
422	invalid_request_error	card_not_active	Card is FROZEN or TERMINATED and cannot process transactions.
422	invalid_request_error	limit_exceeded	Spend would exceed velocity, daily, or monthly limits.
429	rate_limit_error	rate_limited	Key exceeded request quotas. Respect `Retry-After` header.
500	api_error	internal_error	Transient system fault. Safely retry with the same `Idempotency-Key`.

Rate Limits & Backoff

Rate limits are enforced at the API gateway layer per API key. When an application exceeds its allotted rate, the gateway responds with HTTP 429 Too Many Requests and includes the Retry-After header specifying the number of seconds to back off before retrying.