Errors and rate limits
Understand the response envelope, recover from errors, and retry carefully.
Read the error envelope
An error includes a machine-readable error.code, a human-readable error.message, optional details, and a request ID for tracing.
{
"error": {
"code": "PERMISSION_DENIED",
"message": "You do not have permission to perform this action.",
"details": null
},
"meta": {
"request_id": "example-request-id"
}
}Respond to the status code
| Status | Meaning | Next step |
|---|---|---|
| 400 | Validation error | Check parameters and body against the schema. |
| 401 | Unauthenticated | Check or renew the credential and confirm the environment. |
| 403 | Permission denied | Check permissions, facility scope, and IP restrictions. |
| 404 | Not found | Check the resource ID and authorized scope. |
| 409 | Business conflict | Read the message and reason code; resolve the conflict. |
| 429 | Rate limited | Honor Retry-After when present, then back off. |
| 503 | Temporary failure | Read the reason code before deciding to retry. |
Respect rate limits
Limits vary by endpoint and operation. API-key requests are bucketed per key, per route. Do not assume one global requests-per-minute limit for the whole API.
On 429, use Retry-After when supplied. Use bounded exponential backoff with jitter and avoid parallel retry bursts.
Retry writes deliberately
A network timeout does not prove a write failed. Check whether the operation completed before sending it again. Where an endpoint documents Idempotency-Key, reuse the same key only for the same logical operation and unchanged payload.
Idempotency is endpoint-specific. Do not add an undocumented header and assume a payment or resource creation becomes safe to repeat.