Saltar al contenido principal
Every non-2xx response uses the same application/json envelope: 
{
  "code": "invalid_request",
  "detail": "The request is not valid. A parameter is missing, malformed, or out of range. See the errors array for the fields that failed.",
  "errors": [
    { "field": "limit", "code": "too_big", "message": "Must be 100 or less." }
  ]
}
  • code is a stable, machine-readable identifier. Branch your integration on this value. It never changes meaning, so it is safe to compare against.
  • detail is a human-readable sentence meant for logs and debugging. Treat it as informational only: the wording can change at any time, so never match on it.
  • errors is an array of field-level problems, present mainly on invalid_request. Each entry has a field (the parameter that failed), a code (a short reason), and a message (a human explanation). It is an empty array when no single field is at fault.

​
HTTP status codes

The HTTP status reflects the broad category of the failure, while code identifies the exact case:
  • 4xx: the request was rejected as sent. Fix the request before retrying (bad input, missing or invalid key, resource not found).
  • 5xx: the request failed on our side. It is safe to retry, ideally with backoff.

​
Handle unknown codes gracefully

This catalog grows over time. We may add new code values, and new endpoints may return existing codes in new places. Treat the set as open: branch on the codes you know, and fall back to handling anything unrecognized by its HTTP status (for example, retry on 5xx, surface a generic message on 4xx) instead of failing.
CodeHTTPMeaning
invalid_request400The request was rejected during validation. The errors array lists each failing field with a reason, so you can map the failure back to a specific parameter.
unauthorized401Authentication failed: the API key is missing, malformed, or revoked. Send a valid key as a bearer token in the Authorization header. Each key is bound to a single environment (test or live).
invoice_not_found404No invoice matches the supplied identifier in the environment the API key belongs to. An invoice created with a live key is not visible to a test key, and vice versa.
customer_not_found404No customer matches the supplied external_customer_id in the environment the API key belongs to. A customer recorded with a live key is not visible to a test key, and vice versa.
customer_ambiguous409The environment has more than one integration, so external_customer_id on its own does not identify a single customer (the same id can exist in two integrations for different customers). Supply integration_id alongside external_customer_id to scope the session to one integration. You do not need it when the environment has a single integration.
download_link_expired410The download_url returned by the download endpoint has expired or was altered. These links are time-limited bearer URLs; request a new one from the download endpoint rather than storing them indefinitely.
internal_error500An unexpected error occurred on our side. No partial work is persisted, so the request can be retried safely.