Errors - Paygentic

When a request fails, the API returns a 4xx or 5xx status and a JSON body. Every response, failed or not, also has a request-id header.

Error body

{
  "error": "bad_request",
  "message": "A committed billing period would change",
  "code": "INTERVAL_PERIOD_ALREADY_BILLED",
  "details": { "priceKey": "pk_m4n5o6p7q8r9s0t1" },
  "requestId": "105445aa7843bc8bf206b12000100000"
}

Field	Meaning
`error`	The category of the error, such as `bad_request`, `forbidden` or `not_found`. It follows the HTTP status.
`message`	A description for people. Its text can change, so do not parse it in code.
`code`	Optional. A stable code for one failure, such as `TAX_NOT_ENABLED`. Check this field in code.
`details`	Optional. Structured data about the failure.
`requestId`	The id of this request. It has the same value as the `request-id` header.

A request that fails schema validation returns "error": "validation_error" and adds an errors array. Each entry names one field and gives its message.

Request id

The request-id header identifies one request in the Paygentic logs. JSON error bodies also have it in requestId. When you contact support@paygentic.io about a failed request, include the request id. Support can then find the exact request without a search by time and account. Log the request-id header with your own error logs.

Retrying

A 429 or 503 response has a retry-after header that says how many seconds to wait before you send the request again. See Rate limits for how to retry.

Rate limits: the limits and the 429 response
Authentication: how to send your API key