Códigos de error

Estado documental: Contrato propuesto. Los códigos y mensajes pasan a estado implementado o verificado únicamente cuando estén disponibles en la API correspondiente.

Objetivo

Esta página define el formato común de error, el significado de los códigos iniciales y la acción recomendada para cada familia.

Formato común

{
  "error": {
    "code": "validation_error",
    "message": "La solicitud contiene datos inválidos.",
    "fields": {
      "amount": "required"
    },
    "retryable": false,
    "request_id": "req_01JXYZ"
  }
}

Campos del error

Los mensajes pueden mejorar sin cambiar el código. La integración debe tomar decisiones a partir de code, el HTTP status y retryable.

Semántica HTTP

Algunas consultas asíncronas pueden devolver 202 junto con report_not_ready. Ese resultado indica procesamiento en curso, no un fallo irreversible.

Autenticación, ambiente y permisos

Validación y configuración

Idempotencia y duplicados

Órdenes y sesiones de checkout

Turnos, usuarios, dispositivos y entregas

Evidencias, OCR y casos pendientes

Devoluciones

Reportes

Webhooks

Disponibilidad y límites

Reglas de reintento

401 access_token_expired
→ obtener otro token

409 idempotency_conflict
→ no crear otra operación a ciegas

422 validation_error
→ corregir antes de repetir

429 rate_limit_exceeded
→ esperar

503 service_unavailable
→ reintento progresivo con la misma Idempotency-Key

• Un reintento de la misma intención conserva el mismo external_transaction_id, la misma Idempotency-Key y el mismo payload.
• Si una conexión termina sin respuesta, la empresa debe consultar por ID externo antes de crear otra operación.
• Los errores de validación no se reintentan sin corregir los datos.
• Un conflicto 409 requiere consultar el recurso y resolver la causa.
• Los reintentos deben tener un límite y espera progresiva.

Errores desconocidos

Ante un código no reconocido, la empresa debe:

• no asumir éxito;
• conservar HTTP status, code y request_id;
• seguir retryable cuando esté presente;
• evitar mostrar detalles técnicos sensibles al comprador;
• consultar el changelog y la versión del contrato.

Seguridad de los mensajes

Las respuestas no deben publicar secretos, credenciales, stack traces, consultas internas ni detalles privados de infraestructura.

Criterios de aceptación documental

1. Existe un sobre común de error.
2. El código, y no el mensaje, guía la lógica de la integración.
3. request_id permite trazabilidad.
4. retryable informa la posibilidad de reintento.
5. Los 409 no se reintentan a ciegas.
6. Los 422 se corrigen antes de repetir.
7. Los 429 y 503 utilizan espera progresiva.
8. Los reintentos conservan idempotencia.
9. Los errores desconocidos no se tratan como éxito.
10. Las respuestas no exponen información interna.

Payment Orders, Counters y capacidad

Payment Order / API Engine v1.0 separa los errores públicos de la intención de cobro de los conflictos internos que ocurren durante la resolución o adquisición de un Counter.

counter_busy

counter_busy describe el conflicto de adquisición de un Counter específico. En Web Checkout el integrador no selecciona Counters ni conoce un pool: YUPY administra internamente la capacidad runtime del Counter virtual Web canónico.

no_counter_available

Importante: el HTTP status público definitivo de no_counter_available todavía no está cerrado. No debe documentarse 409 ni 503 como contrato final hasta que el API Engine defina esa decisión.

Relación con el medio de pago

El error histórico payment_profile_invalid deja de formar parte del contrato activo de selección del instrumento. El caller solicita payment_method; YUPY resuelve internamente el Counter, la policy y el instrumento concreto habilitado para ese contexto.

Idempotencia en errores de capacidad

Un error de capacidad no autoriza a crear otra intención comercial a ciegas. Si el endpoint permite reintento, debe preservarse external_transaction_id, la intención original y la Idempotency-Key mientras se esté reintentando la misma operación técnica.

Changelog — Payment Order / API Engine

2026-08-09 — Payment Order / API Engine v1.0: se retiró payment_profile_invalid del contrato activo de selección de instrumento; se incorporó 409 counter_busy como conflicto interno de adquisición de un Counter; se añadió no_counter_available como error público de capacidad del pool sin fijar todavía su HTTP status final; y se aclaró que los reintentos de capacidad deben conservar la intención e idempotencia cuando el endpoint los permita.