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

# Errores

> Cómo reporta Payzor los errores y qué significa cada código de estado.

# Errores

Payzor devuelve errores en JSON junto con un código de estado HTTP:

```json theme={null}
{ "error": "Saldo insuficiente. Disponible: $56 USDC" }
```

## Códigos de estado

| Estado | Significado                             | Causa típica                                                                                                                    |
| ------ | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | Petición mal formada                    | Campo ausente o inválido (`amountUsdCents` que no es un entero positivo, dirección incorrecta...).                              |
| `401`  | Sin autenticar                          | Credencial ausente o equivocada; el mensaje dice cuál se esperaba.                                                              |
| `402`  | Pago requerido / rechazado por política | Presupuesto excedido, tope por cargo, o los límites duros del agente bloquearon el pago. El cuerpo explica exactamente por qué. |
| `403`  | Prohibido                               | Credencial válida con el alcance equivocado (por ejemplo, el recurso de otro comercio) o dirección bloqueada por KYT.           |
| `404`  | No encontrado                           | Id desconocido de cargo, PayLink o endpoint.                                                                                    |
| `409`  | Conflicto                               | Operación inválida para el estado actual (pagar un cargo ya pagado, PayLink caducado).                                          |
| `500`  | Error del servidor                      | Bug o problema de infraestructura. Se puede reintentar sin riesgo.                                                              |
| `503`  | Servicio no disponible                  | La función requiere PostgreSQL y no está configurado; o el facilitador x402 no responde.                                        |

## Los rechazos de política a veces son 200

Un matiz que conviene conocer: cuando un agente paga un cargo y su **política** bloquea o pausa el pago, el endpoint sigue respondiendo `200` con un resultado estructurado en vez de un código de error:

```json theme={null}
{ "paid": true, "charge": { "...": "..." } }                        // liquidado
{ "pendingApproval": true, "approvalId": "...", "reason": "..." }   // pausado para el humano
{ "error": "Categoría 'services' no está ..." }                     // bloqueado (HTTP 402)
```

Los agentes son programas que se ramifican según el resultado; darles un motivo legible por máquina es más útil que un código de estado a secas.

## Cómo diseñar tu integración alrededor de los errores

1. **Ramifica según los tres resultados de pago**, no solo entre éxito y fallo.
2. **Parsea los errores de presupuesto**: `excede_presupuesto_restante_350` lleva dentro los centavos exactos que quedan.
3. **Reintenta solo en 5xx.** Un 4xx significa que tu entrada o tu estado están mal; repetir no va a ayudar.
4. **Registra los valores de `reference`** de los pagos exitosos; coinciden entre los cargos del comercio y los rastros de auditoría de los agentes.