Manejo de errores

Formato de error estandar

Todas las respuestas de error siguen este formato:

json

{
  "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 > Configuración > 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 (codigo 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

Pagos recurrentes

Mensajes propios de /subscriptions (mismo formato de error). Usa el message y el HTTP para decidir; el code es el generico de validacion o de recurso.

Recurso no encontrado (404)

Mensaje	Cuando
`Subscription not found`	No existe, es de otro webcode o del otro entorno (Live/Test)
`Subscription link not found`	Igual, para links de pago recurrente

Accion no permitida en el estado actual (400)

Mensaje	Cuando
`Only active subscriptions can be paused. Current status: X`	`pause` sobre uno que no esta `active`
`Cancelled subscriptions cannot be reactivated`	`reactivate` o `update-card` sobre uno cancelado (igual que en el panel)
`Cancelled subscriptions cannot be updated`	`PATCH` sobre uno cancelado
`Payment link cannot be completed. Current status: X`	Cancelar o simular un link que ya no esta pending

Validacion (400)

Mensaje	Como evitarlo
`intervalCount must be at least 1`	Entero >= 1
`billingDay is only allowed when intervalUnit is month`	Envia `billingDay` solo con `intervalUnit: month`
`billingDay must be between 1 and 31`	1-31
`endAt must be a future date`	`Y-m-d` o `Y-m-d H:i:s` posterior a hoy
`Invalid status filter`	`status` de los permitidos para ese listado
`Invalid cursor`	Reutiliza tal cual el `nextCursor` recibido
`reason must be 1-64 characters`	`reason` de `cancel`: minusculas, numeros y `_`
`Fields not allowed: ...`	Solo los campos documentados en `PATCH`
`No update data provided`	`PATCH` con al menos un campo
`Invalid result. Allowed: ...`	Simuladores Test: `success`, `declined`, `not_enough_balance`, `card_expired`, `error`

Ejemplo de respuesta de error

json

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

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
Pagos recurrentes: intervalUnit en day, week, month, year; intervalCount >= 1; billingDay (1-31) solo con month; endAt futura; returnUrl http/https