> For the complete documentation index, see [llms.txt](https://docs.peakcommerce.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.peakcommerce.com/developers/api-reference/errors.md).

# Errors

Errors are returned as JSON with this base shape:

```json
{
  "error": { "code": "insufficient_scope", "message": "Human-readable message" },
  "requestId": "req_3f9a1c2b7d4e8f60"
}
```

`error.code` is stable and machine-readable; `error.message` is human-facing. Some errors attach extra fields as documented below. Key your retry and handling logic off the HTTP status and `error.code`. The same `requestId` is returned in the `X-Request-ID` response header; quote it when you contact support.

Validation errors carry a code and per-field `details`:

```json
{
  "error": {
    "code": "validation_failed",
    "message": "Request validation failed.",
    "details": [
      { "field": "currency", "message": "Required" }
    ]
  },
  "requestId": "req_3f9a1c2b7d4e8f60"
}
```

A request blocked by one of your policies returns `403` with the code `policy_violation`; the message is the blocking policy's reason:

```json
{
  "error": {
    "code": "policy_violation",
    "message": "Order exceeds maximum unapproved amount"
  },
  "requestId": "req_3f9a1c2b7d4e8f60"
}
```

## Status codes

| Status                      | Meaning                                                                                                       |
| --------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `200 OK`                    | Request succeeded                                                                                             |
| `201 Created`               | Resource created                                                                                              |
| `204 No Content`            | Request succeeded, nothing to return (used by `DELETE`)                                                       |
| `400 Bad Request`           | Validation failed; body malformed; required parameter missing                                                 |
| `401 Unauthorized`          | API key missing, unknown, or revoked                                                                          |
| `403 Forbidden`             | Authenticated but the key lacks required scope, or a policy blocked the operation                             |
| `404 Not Found`             | Resource does not exist for the calling tenant                                                                |
| `409 Conflict`              | Terminal-state conflict (e.g. completing an already-completed payment)                                        |
| `413 Payload Too Large`     | Request body is larger than 1 MB; see [Request size limits](#request-size-limits)                             |
| `429 Too Many Requests`     | Rate limit exceeded; see [Rate limits](https://docs.peakcommerce.com/developers/api-reference/rate-limits.md) |
| `500 Internal Server Error` | Bug on our side — safe to retry idempotent requests                                                           |
| `502 Bad Gateway`           | Downstream billing system returned an error or could not be reached                                           |

## Common error codes

| `error.code`             | Status | When it appears                                                                                                                                                                   |
| ------------------------ | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `validation_failed`      | 400    | The request body or parameters failed validation; see `details`                                                                                                                   |
| `api_key_required`       | 401    | No API key was sent                                                                                                                                                               |
| `invalid_api_key`        | 401    | The API key is not recognized                                                                                                                                                     |
| `api_key_revoked`        | 401    | The API key has been revoked                                                                                                                                                      |
| `insufficient_scope`     | 403    | The API key lacks a scope the endpoint requires                                                                                                                                   |
| `policy_violation`       | 403    | One of your policies blocked the operation                                                                                                                                        |
| `not_found`              | 404    | The resource (for example an account or subscription) does not exist for your tenant                                                                                              |
| `user_email_conflict`    | 409    | A user with this email already exists in your tenant (`POST /api/v1/users`, or `PATCH /api/v1/users/{id}` changing the email); the comparison ignores case and surrounding spaces |
| `no_billing_integration` | 404    | The endpoint needs an active billing integration (Stripe or Zuora) and none is configured                                                                                         |
| `rate_limit_exceeded`    | 429    | You exceeded your key's rate limit; see [Rate limits](https://docs.peakcommerce.com/developers/api-reference/rate-limits.md)                                                      |
| `internal_error`         | 500    | An error on our side; safe to retry idempotent requests                                                                                                                           |
| `live_quote_unavailable` | 502    | The order needs live billing-system pricing, but the billing integration cannot quote it                                                                                          |
| `live_quote_failed`      | 502    | The live billing-system quote was attempted and failed                                                                                                                            |

## Request size limits

* **Body size.** A JSON request body may be at most 1 MB. A larger body is refused with `413 Payload Too Large`.
* **Lists and maps.** Arrays and key–value maps in a request body have a maximum length (for example, the line items of an order or the event types of a webhook). Limits vary by field and are set above observed production use. An over-limit list or map returns `400` with the error code `validation_failed` and one detail naming the field, its length and the limit:

```json
{
  "error": {
    "code": "validation_failed",
    "message": "Request validation failed.",
    "details": [
      { "field": "items", "message": "At most 200 items allowed; received 5000" }
    ]
  },
  "requestId": "req_3f9a1c2b7d4e8f60"
}
```

If a list is over its limit, the response reports the size error instead of item-level errors. Split the request or send fewer entries.

## Retrying

* `4xx` errors should not be retried without changing the request.
* `429` should be retried after `X-RateLimit-Reset` (a Unix timestamp).
* `5xx` errors are safe to retry; use exponential backoff. Be aware that the API does not currently de-duplicate retried writes server-side, so guard against duplicates client-side (e.g. don't retry a `POST` that may have succeeded without first checking via `GET`).

## Related

* [Rate limits](https://docs.peakcommerce.com/developers/api-reference/rate-limits.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.peakcommerce.com/developers/api-reference/errors.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
