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:

{
  "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.