Errors
Standard error response format and status codes.
All error responses follow a consistent JSON structure:
{
"error": "not_found",
"message": "User not found for the authenticated partner",
"requestId": "req-a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}The requestId field is included in every error response. Include this
value when contacting support for faster issue resolution.
Status Codes
| Code | Error Key | Description |
|---|---|---|
400 | bad_request | Invalid request shape or malformed parameters |
401 | unauthorized | API key or HMAC authentication failed |
404 | not_found | User or resource not found for the authenticated partner |
409 | conflict | Request conflicts with current resource state (e.g. duplicate externalId) |
422 | unprocessable_entity | Business validation failed (e.g. user under 18) |
429 | too_many_requests | Rate limit exceeded — check the Retry-After header |
500 | internal_error | Unexpected server failure |
Field Errors
When multiple fields fail validation, the response includes a fieldErrors array:
{
"error": "bad_request",
"message": "Request body failed validation",
"requestId": "req-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"fieldErrors": [
{ "field": "email", "message": "Must be a valid email address" },
{ "field": "dateOfBirth", "message": "Must be a valid date in YYYY-MM-DD format" }
]
}