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

# Errors

> Every error uses the RFC 7807 problem format. Classify by HTTP status, not the body.

When a request fails, the gateway returns a problem response with
`Content-Type: application/problem+json` and a consistent shape. The **HTTP
status** is what you branch on; the body explains the detail.

## Problem shape

```json theme={null}
{
  "type": "https://errors.zeam.app/validation-error",
  "title": "Validation Error",
  "status": 422,
  "detail": "The 'amount' field must be a positive decimal.",
  "instance": "/v1/quotes",
  "requestId": "01J8Z6K3QW9F2",
  "errors": [
    { "field": "amount", "message": "must be > 0" }
  ]
}
```

<ResponseField name="type" type="string">
  A stable URI identifying the error category, under `https://errors.zeam.app/`.
</ResponseField>

<ResponseField name="title" type="string">
  Short, human-readable summary of the category.
</ResponseField>

<ResponseField name="status" type="integer">
  The HTTP status code, repeated in the body.
</ResponseField>

<ResponseField name="detail" type="string">
  A human-readable, actionable explanation of this specific failure.
</ResponseField>

<ResponseField name="instance" type="string">
  The path that produced the error.
</ResponseField>

<ResponseField name="requestId" type="string">
  Mirrors the `X-Request-Id` response header. Quote it in support requests.
</ResponseField>

<ResponseField name="errors" type="array">
  Field-level validation failures, when applicable. Each item has a `field` and
  a `message`.
</ResponseField>

## Error catalogue

| Status | `type` suffix      | When it happens                                                                   |
| ------ | ------------------ | --------------------------------------------------------------------------------- |
| `400`  | `validation-error` | Malformed body or query parameters.                                               |
| `401`  | `unauthenticated`  | Missing or invalid bearer token or `x-zeam-auth`. Generic by design.              |
| `403`  | `forbidden`        | Authenticated, but not permitted for this action.                                 |
| `404`  | `not-found`        | The wallet, intent, or other resource does not exist.                             |
| `422`  | `validation-error` | The body parsed but failed field validation; see `errors`.                        |
| `429`  | `rate-limited`     | Too many requests. Honor `Retry-After`. See [rate limits](/platform/rate-limits). |
| `502`  | `upstream-error`   | A downstream service returned an unexpected error.                                |
| `504`  | `upstream-timeout` | A downstream service timed out.                                                   |
| `500`  | `internal-error`   | An unexpected error in the gateway.                                               |

## Handling guidance

* **Branch on the HTTP status**, then read `type` for the specific category.
* **`401`** is intentionally generic and never says which credential failed.
  Re-authenticate and retry with valid credentials.
* **`429`, `502`, `504`** are transient. Retry with backoff; for `429`, wait for
  `Retry-After`.
* **`400`, `422`** are caused by the request. Fix the input using `detail` and
  `errors`, then retry.
* Always capture `requestId` so Zeam can trace the exact request.