# Errores

Qué significa cada respuesta que no es `2xx`, y qué hacer con ella.

## Los que vas a ver integrando

| Código | Qué pasó                                               | Qué hacer                                                                                                                            |
| ------ | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
| `400`  | Falta el header `Idempotency-Key`.                     | Mándalo. Es obligatorio en todo cobro.                                                                                               |
| `400`  | La `urlRetorno` no es de tu sitio.                     | Tiene que ser de tu dominio registrado o un subdominio suyo, y empezar por `https`. Si cambiaste de dominio, actualízalo en Ajustes. |
| `401`  | La llave no sirve.                                     | Está mal copiada, o la rotaste y quedó la anterior en tu configuración.                                                              |
| `409`  | No tienes registrado tu sitio ni tu página de retorno. | Se configuran una vez en el portal, en Ajustes. Sin eso no se puede cobrar, porque el comprador se quedaría sin forma de volver.     |
| `409`  | Tu comercio no está aprobado todavía.                  | Falta que EvePay lo apruebe. Escríbenos.                                                                                             |
| `409`  | Esa `Idempotency-Key` ya se usó con otro cuerpo.       | Dos pedidos distintos están compartiendo clave. Usa una por pedido, estable entre reintentos.                                        |
| `503`  | La pasarela no respondió.                              | No es un fallo de tu petición. Viene con `Retry-After`: reintenta con **la misma** `Idempotency-Key` y no se duplica nada.           |

> **La diferencia entre 503 y 400 es deliberada.** Un `503` te dice «vuelve a intentar»; un `400`, «algo de tu petición está mal y reintentar no ayuda». Distinguirlos evita que tu sistema reintente en bucle contra un error que nunca se va a arreglar solo.

## Cómo vienen

Los errores de validación traen el detalle por campo, para que sepas cuál corregir sin adivinar:

```json
{
  "statusCode": 400,
  "message": {
    "formErrors": [],
    "fieldErrors": {
      "urlRetorno": [
        "Debe ser una dirección https completa, por ejemplo https://tutienda.co/gracias"
      ]
    }
  }
}
```

## Un pago aprobado que no te llegó

Si el comprador dice que pagó y tu sistema no se enteró, el aviso no llegó o se perdió. Consulta `GET /v1/pagos/:id`: ese es el estado real. Si está `aprobado`, el cobro existe y la plata también; lo que falló fue la entrega del aviso.