Manejo de Errores

Formato de error estandar

Todas las respuestas de error siguen este formato:

{
  "success": false,
  "error": {
    "message": "Descripcion legible del error",
    "code": 12001,
    "statusCode": 400,
    "traceId": "abc123def456..."
  }
}

Campo	Descripcion
`message`	Descripcion del error en ingles
`code`	Codigo interno de error (ver tabla abajo)
`statusCode`	Codigo HTTP de la respuesta
`traceId`	Identificador unico para soporte tecnico

Nota de seguridad: Los errores internos del servidor (5xx) devuelven un mensaje generico ("An error has occurred...") para no exponer detalles de implementacion. El traceId permite al equipo de soporte investigar el error concreto.

Nota sobre entornos: Los codigos de error, formatos y mensajes son identicos en los entornos Live y Test. No hay diferencias en el manejo de errores entre entornos.

Catalogo de codigos de error

Errores de autenticacion y autorizacion (11xxx)

Codigo	HTTP	Descripcion	Accion recomendada
11001	403	API key invalida o no proporcionada	Verifica la cabecera `X-API-KEY`
11002	403	IP no permitida	Configura tu IP en el dashboard (Integraciones > API Keys)
11008	403	Acceso denegado al recurso	El webcode no coincide, el pago no pertenece a la External API, o error de entorno

Errores de validacion (12xxx)

Codigo	HTTP	Descripcion	Accion recomendada
12001	400	Parametro requerido faltante o formato invalido	Revisa los campos obligatorios y sus formatos
12002	400	Fecha en formato incorrecto	Usa formato ISO 8601 (ej: `2026-07-15T14:00:00Z`)
12006	400	Formato de pais invalido	Usa ISO 3166-1 alpha-2 (ej: `ES`, `FR`, `DE`)
12009	400	Pais no soportado	Consulta con soporte la lista de paises disponibles

Errores de recurso (10xxx)

Codigo	HTTP	Descripcion	Accion recomendada
10404	404	Recurso no encontrado	Verifica que el `sessionId` o `paymentReference` sea correcto

Errores de POS (13xxx)

Codigo	HTTP	Descripcion	Accion recomendada
13001	500	Error del proveedor de pagos	Reintenta despues de unos segundos. Si persiste, contacta soporte
13004	502	Error de comunicacion con el terminal	Verifica que el terminal esta encendido y conectado
13005	409	Terminal ocupado	Espera a que termine la transaccion en curso e intenta de nuevo

Conflictos de idempotencia (409)

Estos conflictos no llevan un codigo numerico interno: el mensaje permite distinguirlos del 409 de POS ocupado (13005).

Caso	HTTP	Mensaje (literal)	Accion recomendada
Misma `Idempotency-Key`, body distinto	409	`Idempotency key reused with a different request body.`	Usa una clave nueva o reenvia el mismo body que la peticion original
Misma `Idempotency-Key`, otro endpoint	409	`Idempotency key already used for a different endpoint.`	No reutilizar la misma clave entre endpoints distintos

Errores internos (99xxx)

Codigo	HTTP	Descripcion	Accion recomendada
99001	500	Error interno del servidor	Anota el `traceId` y contacta soporte

Ejemplo de respuesta de error

{
  "success": false,
  "error": {
    "message": "External device is busy.",
    "code": 13005,
    "statusCode": 409,
    "traceId": "b2f3d36dc305249e8d1ebaa49ef616f1"
  }
}

Buenas practicas

Reintentos

Errores 4xx: No reintentes (el problema esta en la peticion)
Errores 5xx: Reintenta con backoff exponencial (1s, 2s, 4s, 8s...)
409: si es 13005 (terminal ocupado), espera 5-10 segundos y reintenta. Si el mensaje empieza por Idempotency key…, no reintentes a ciegas: corrige la clave o el body de la peticion
Siempre usa Idempotency-Key para que los reintentos sean seguros (pero asegurate de no reutilizarla con body distinto)

Logging

Registra el traceId de las respuestas de error para facilitar la comunicacion con soporte tecnico.

Validacion previa

Valida los datos antes de enviar la peticion para evitar errores 400:

amount.value debe ser un entero positivo (centimos)
amount.currency debe ser exactamente 3 letras mayusculas (EUR, GBP o USD)
webcode no puede estar vacio
URLs (urlOk, urlKo) deben ser URLs validas con protocolo
reason en reembolsos debe ser uno de los 5 valores exactos permitidos

Documentación para desarrolladores