> 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

Most errors are returned as JSON with this base shape:

```json
{ "error": "Human-readable message" }
```

The exact field set varies by error type — every body has an `error` string, and some bodies attach extra fields (`issues`, `policy`, `liveQuoteAvailable`) as documented below. Treat the `error` string as human-facing; key your retry/handling logic off the HTTP status and the extra fields.

Validation errors include `issues`:

```json
{
  "error": "validation_failed",
  "issues": [
    { "path": ["currency"], "message": "Required", "code": "invalid_type" }
  ]
}
```

Policy-blocked operations include the offending policy:

```json
{
  "error": "Order exceeds maximum unapproved amount",
  "policy": { "name": "Max order amount", "type": "order_create" }
}
```

## 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)            |
| `429 Too Many Requests`     | Rate limit exceeded; see [Rate limits](/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` value                              | When it appears                                                            |
| ------------------------------------------ | -------------------------------------------------------------------------- |
| `validation_failed`                        | Request body failed Zod validation                                         |
| `Insufficient scope. …`                    | API key lacks required scope                                               |
| `Account not found`                        | Account ID does not match a tenant-owned account or billing-system account |
| `Subscription not found`                   | Subscription ID does not exist for this tenant                             |
| `No active billing integration configured` | Endpoint needs Stripe/Zuora but none is active                             |
| `Live billing-system quote failed: …`      | Order contains non-modeled charges and the live quote roundtrip failed     |
| `Rate limit exceeded. Try again later.`    | You exceeded your key's rate limit                                         |

## 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](/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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.