Errors

Errors always have this shape:

{
  "error": {
    "type": "invalid_state_error",
    "code": "insufficient_balance",
    "message": "Available balance is lower than the amount plus fee.",
    "param": "amount",
    "request_id": "req_02"
  }
}

• type groups errors. code is a stable machine-readable value that does not change within a major version. Match on code, not on message.
• message is in English and meant for people.
• param names the offending parameter, if any.
• request_id identifies the request. Include it when you contact support.
• New codes may be added without a new version: handle unknown codes by HTTP status.

Catalog

HTTP	type	code	Retry	Meaning
400	invalid_request_error	parameter_invalid, parameter_missing, amount_out_of_range	no	The request is invalid.
401	authentication_error	api_key_invalid, api_key_revoked	no	The key is not accepted.
403	permission_error	merchant_not_active, method_not_allowed, country_not_allowed	no	Not permitted.
404	not_found_error	resource_not_found	no	Object not found.
409	idempotency_error	idempotency_conflict, idempotency_in_progress	depends	Idempotency key conflict.
422	invalid_state_error	invalid_state, insufficient_balance, method_not_available, blocked_payer, limit_exceeded	no	The request is valid but the current state does not allow it.
429	rate_limit_error	rate_limited	yes, after Retry-After	Too many requests.
500	api_error	internal_error	yes	Server error.
502, 503	api_error	provider_unavailable, service_unavailable	yes	Provider or service unavailable.

409 idempotency_conflict is not retryable as is; 409 idempotency_in_progress is, after Retry-After.

After a network error or a 5xx, retry with the same Idempotency-Key. See Idempotency.