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

# Errors

> Every API error follows the same format — and each one tells you what to do.

Every error response (4xx/5xx) follows [RFC 7807](https://datatracker.ietf.org/doc/html/rfc7807) — the same shape, always:

```json theme={"system"}
{
  "type": "ERR_INTEGRATION_006",
  "title": "Método não disponível",
  "status": 422,
  "detail": "O método de pagamento informado não está habilitado no projeto.",
  "instance": "/api/v1/transactions"
}
```

| Field                | What it is                                                                       |
| -------------------- | -------------------------------------------------------------------------------- |
| `type` / `errorCode` | The **stable** error code — use it in your code, not the message                 |
| `title`              | Short human-readable title                                                       |
| `status`             | HTTP status (repeated in the body)                                               |
| `detail`             | Explanation of what happened                                                     |
| `instance`           | Path of the request that failed                                                  |
| `details`            | Extras when present — e.g. `issues` with the invalid fields on validation errors |

<Tip>
  Handle errors by `status` + `type`. The messages (`title`/`detail`) may improve over time; the codes don't change.
</Tip>

## What to do with each status

| Status | Meaning                                                 | What to do                                                                                                                                                                                 |
| ------ | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `400`  | Invalid payload (validation)                            | **Don't retry** without fixing it. Check `details.issues` — it lists field by field what failed.                                                                                           |
| `401`  | API key missing, invalid, or revoked                    | Check the `Authorization: Bearer sk_...` header and that the key wasn't revoked in the Dashboard.                                                                                          |
| `403`  | Authenticated, but no permission                        | Check the key type and the project mode (a sandbox project blocks `sk_live_`).                                                                                                             |
| `404`  | Resource not found                                      | Wrong ID or from another project — the API doesn't reveal other people's resources.                                                                                                        |
| `409`  | `Idempotency-Key` in processing                         | Another request with the same key is in flight. Wait \~1s and retry **with the same key** — you get the replay. See [Idempotency](/en/pages/idempotency).                                  |
| `422`  | Semantic error                                          | The payload is valid, but a business rule blocks it: method not available, amount above the project limit, an idempotency key reused with a different body. Fix the cause before retrying. |
| `429`  | Rate limit                                              | Wait for the `Retry-After` header (seconds) before retrying. Exponential backoff if it persists.                                                                                           |
| `500`  | Internal error                                          | Retry with backoff. If it persists, contact support with the `instance` and the time.                                                                                                      |
| `503`  | Processing temporarily unavailable or system under load | Transient — retry with backoff. On transaction creation, use an [Idempotency-Key](/en/pages/idempotency) to retry without the risk of duplicating.                                         |

## Codes you'll encounter

| `type`                | Status | When it happens                                                |
| --------------------- | ------ | -------------------------------------------------------------- |
| `ERR_VALIDATION_001`  | 400    | Invalid fields in the body/query (details in `details.issues`) |
| `ERR_AUTH_009`        | 401    | Invalid or expired API key                                     |
| `ERR_AUTHZ_001`       | 403    | Key without the required permission for the resource           |
| `ERR_TRANSACTION_001` | 404    | Transaction not found                                          |
| `ERR_INTEGRATION_006` | 422    | Payment method not available on the project                    |

## Special case: HTTP 202 on creation

`202` **is not an error** — it's a partial success. The PIX was generated, but persistence is pending automatic reconciliation:

* `data.id` comes back `null`; use `data.externalId` as the reference
* The `pixCode` is **valid and payable** — deliver it to the buyer as usual
* The transaction appears in the listing within a few minutes, after reconciliation

## Timeouts

Transaction creation can take up to **30 seconds** in the worst case. Set your HTTP client's timeout above that (the [SDK](/en/pages/sdk/node) uses 35s) and, when retrying after a timeout, **use the same `Idempotency-Key`** — if creation completed, you get the replay instead of a duplicate payment.

## Next steps

<CardGroup cols={2}>
  <Card title="Idempotency" icon="rotate" href="/en/pages/idempotency">
    Resend creations safely after a timeout.
  </Card>

  <Card title="Configure webhooks" icon="webhook" href="/en/pages/webhooks">
    Handle the payment result asynchronously.
  </Card>
</CardGroup>