> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paygentic.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> The shape of an error response, how to tell errors apart, and the request id to send to support.

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

```json theme={null}
{
  "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](mailto: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](https://docs.paygentic.io/rate-limits.md) for how to retry.

## Related pages

* [Rate limits](https://docs.paygentic.io/rate-limits.md): the limits and the `429` response
* [Authentication](https://docs.paygentic.io/authentication.md): how to send your API key


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.