Errors
All as-built endpoints return JSON errors with Content-Type: application/json:
{
"code": "validation_error",
"message": "amount must be a positive integer (minor units)"
}
code | Typical HTTP status |
|---|---|
validation_error | 400 |
unauthorized | 401 |
forbidden | 403 |
not_found | 404 |
conflict | 409 |
rate_limited | 429 |
internal_error | 500 |
upstream_error | 502 |
Optional details may be present for structured diagnostic context. This is not RFC 7807 Problem Details.
The response does not currently include a Retry-After header on 429s.
Two different kinds of 429
A 429 with {"code": "rate_limited", ...} comes from this service's own code — typically a rate limit hit on an upstream provider (BasisTheory or Coinflow) while handling your request. It follows the shared error shape above.
A 429 with a body like {"message": "Too Many Requests"} (no code field) comes from API Gateway's own request throttling, enforced ahead of this service's code. It does not follow the {code, message} shape — there's no supported way to customize that response body on this API's gateway type. If you see this shape, back off and retry with backoff; it means you've exceeded the platform-level rate limit, independent of anything this service's error handling controls.