Errores
Forma de las respuestas de error, códigos estables y qué reintentar.
Todas las respuestas de error son JSON con un código estable en error, un mensaje legible en message, la hora en timestamp y la ruta en path. Programa contra error, nunca contra el texto de message.
{
"statusCode": 401,
"timestamp": "2026-11-19T18:00:00.000Z",
"path": "/api/v1/me",
"error": "invalid_api_key",
"message": "La llave de API no es válida."
}Un campo no declarado o con tipo inválido responde con el 400 estándar de validación:
error es Bad Request y message es un arreglo con un texto por campo.curl "$CLOBEPAY_API_BASE/me"Respuesta esperada: HTTP 401
Qué hacer con cada código
| HTTP | Significado | Acción |
|---|---|---|
| 400 | Petición inválida (validación, falta Idempotency-Key, credenciales ambiguas) | Corrige la petición. No reintentes igual. |
| 401 | Credencial ausente, inválida, revocada, expirada o de otro entorno | Revisa la llave. No reintentes. |
| 403 | Sin scope o comercio no operativo | Revisa permisos o el estado del comercio. |
| 404 | No existe o pertenece a otro comercio | Revisa el identificador. |
| 409 | Conflicto de estado (verificación no aprobada, petición idempotente en curso) | Corrige el estado; si es idempotency_request_in_progress, reintenta. |
| 422 | Regla de negocio (importe, Idempotency-Key reutilizada, URL no permitida) | Corrige el cuerpo. |
| 429 | Límite de peticiones | Espera lo que indique Retry-After y reintenta. |
| 5xx | Error transitorio | Reintenta con espera creciente y la misma Idempotency-Key. |
Timeouts y errores de red
El resultado es incierto: no crees otra operación. Reintenta con la misma Idempotency-Key o consulta el recurso. Registra error, path y timestamp en tus logs, sin datos personales ni secretos.