API
Errores
Todos los errores usan channel.error.v1:
{
"schema_version": "channel.error.v1",
"error": { "code": "IDEMPOTENCY_CONFLICT", "retry_class": "DO_NOT_RETRY" },
"correlation_ref": "cor_…"
}field aparece cuando el error apunta a un campo concreto (order.total, por ejemplo). Guarda correlation_ref para soporte. Nunca se devuelven datos de otros comercios ni detalles internos.
retry_class#
| Clase | Qué hacer |
|---|---|
DO_NOT_RETRY | No reintentes sin cambiar la solicitud. |
RETRY_SAME_KEY | Reintenta con la misma Idempotency-Key y el mismo cuerpo. |
RETRY_AFTER | Espera Retry-After segundos. |
POLL_READBACK_ONLY | Consulta el readback; no reenvíes. |
Códigos#
| HTTP | Código | Reintento |
|---|---|---|
| 400 | INVALID_REQUEST | DO_NOT_RETRY |
| 400 | UNKNOWN_FIELD | DO_NOT_RETRY |
| 400 | FORBIDDEN_FIELD | DO_NOT_RETRY |
| 400 | IDEMPOTENCY_KEY_REQUIRED | DO_NOT_RETRY |
| 400 | MALFORMED_HEADER | DO_NOT_RETRY |
| 401 | INVALID_CREDENTIALS | DO_NOT_RETRY |
| 401 | SIGNATURE_INVALID | DO_NOT_RETRY |
| 401 | TIMESTAMP_OUT_OF_WINDOW | DO_NOT_RETRY |
| 403 | INTEGRATION_REVOKED | DO_NOT_RETRY |
| 403 | INSUFFICIENT_SCOPE | DO_NOT_RETRY |
| 403 | CHANNEL_NOT_ENABLED | DO_NOT_RETRY |
| 404 | RESOURCE_NOT_FOUND | DO_NOT_RETRY |
| 405 | METHOD_NOT_ALLOWED | DO_NOT_RETRY |
| 409 | IDEMPOTENCY_CONFLICT | DO_NOT_RETRY |
| 409 | OPERATION_PENDING | POLL_READBACK_ONLY |
| 413 | PAYLOAD_TOO_LARGE | DO_NOT_RETRY |
| 415 | UNSUPPORTED_MEDIA_TYPE | DO_NOT_RETRY |
| 423 | VALIDATIONS_EXHAUSTED | DO_NOT_RETRY |
| 429 | RATE_LIMITED | RETRY_AFTER |
| 503 | SERVICE_UNAVAILABLE | RETRY_SAME_KEY |
503 incluye plazo vencido, fallas de dependencias y estados que el servicio no puede decidir con seguridad. No consume cupo.
CHANNEL_NOT_ENABLED también se devuelve cuando el comercio todavía no está habilitado en la modalidad que usas (ver canales).