Concepts
Errors
HTTP status codes returned by the Buvei API.
The API uses conventional HTTP status codes. The response body is always the unified error envelope.
| Code | Meaning | Typical cause |
|---|---|---|
400 | Bad Request | Missing or malformed parameters — see errors map for the offending field |
401 | Unauthorized | Invalid API key, expired timestamp, or bad signature |
403 | Forbidden | IP not whitelisted, or signature/auth header mismatch |
404 | Not Found | Resource doesn't exist or is not visible to your project |
409 | Conflict | Duplicate request — usually a re-used nonce or idempotency key |
429 | Too Many Requests | Rate limit exceeded |
500 | Internal Server Error | Buvei-side incident. Retry with exponential back-off; if it persists, contact support with the X-Request-ID. |
Distinguishing 401 vs 403
Both indicate "authentication problem", but the resolution is different.
401— the credentials would be acceptable but something about this request is invalid: clock drift, bad signature, replayed nonce.403— the credentials cannot speak to the server at all: IP not whitelisted, or your project lacks access to the resource.
Inspect the message field; it always names the specific cause.
Example
{
"code": 400,
"message": "Invalid request parameter",
"errors": {
"amount": "Amount must be positive",
"cardBinId": "Card BIN ID is required"
}
}