Errors

Every error returns the standard envelope with a stable code you can branch on. The HTTP status mirrors the error class, so you can handle failures by code in your application and by status at the edge.

{
  "status": false,
  "error": {
    "code": "insufficient_funds",
    "message": "The balance is insufficient for this operation.",
    "details": {}
  }
}

Error codes

Code	HTTP	Meaning
`validation_error`	400	The request was invalid.
`authentication_failed`	401	Authentication credentials were invalid.
`signature_invalid`	401	The request signature is missing, expired, or invalid.
`compliance_block`	403	This transaction was blocked by compliance.
`permission_denied`	403	This API key is not permitted to perform that action.
`not_found`	404	The requested resource was not found.
`idempotency_conflict`	409	This Idempotency-Key was already used with a different request.
`rate_expired`	409	The quoted rate has expired. Request a fresh quote.
`insufficient_funds`	422	The balance is insufficient for this operation.
`limit_exceeded`	422	This operation exceeds a configured limit.
`rate_limited`	429	Too many requests. Slow down and retry.
`provider_unavailable`	502	An upstream provider is unavailable. Try again shortly.
No error codes match that filter.

4xx your request — fix and retry. 5xx upstream/provider — safe to retry with the same idempotency key.