API reference
Errors
Every error has a type, a code, a message and the requestId. Branch on type and code, never on message text.
Shape
Error shape
{
"error": {
"type": "invalid_request_error",
"code": "validation_error",
"message": "A valid fiatAmount is required.",
"field": "fiatAmount",
"requestId": "req_3f0c9a1b2c4d5e6f7a8b9c0d"
}
}requestId matches the X-Request-Id response header (always a BOSPay req_… ID). Quote it to support. An X-Request-Id you send comes back as X-Client-Request-Id and is logged with the request. Unexpected server errors never include internal details.
Codes
| Status | Code | Type | Retry? |
|---|---|---|---|
| 400 | validation_error | invalid_request_error | No. Fix the parameter named in field. |
| 400 | unsupported_version | invalid_request_error | No. Send a supported BOSPay-Version. |
| 401 | authentication_failed | authentication_error | No. Use an active key for this environment. |
| 403 | permission_denied | permission_error | No. The key lacks the permission or is publishable, the action is console-only or admin-only, or the organization is suspended. |
| 403 | verification_required | permission_error | No. Live payments need a verified organization: an admin verifies in the console under Verification. Sandbox is unaffected. |
| 404 | not_found | invalid_request_error | No. Check the ID and the key's environment. |
| 409 | idempotency_conflict | idempotency_error | No. The key was used with a different body. |
| 409 | idempotency_in_progress | idempotency_error | Yes, shortly, with the same key. |
| 409 | operation_uncertain | idempotency_error | No. An earlier request with this key failed without a clear result; check, then ask an admin to resolve it. |
| 409 | state_conflict | invalid_request_error | No. The object's state does not allow it. |
| 429 | rate_limited | rate_limit_error | Yes, after Retry-After. |
| 500 | internal_error | api_error | Yes, with the same Idempotency-Key. |
| 503 | temporary_failure | api_error | Yes, with backoff and the same Idempotency-Key. |
Clients pinned to 2026-09-16 receive idempotency_conflict, validation_error, temporary_failure and permission_denied in place of idempotency_in_progress and operation_uncertain, state_conflict, internal_error, and verification_required.