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.

Forma del error
{
  "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."
}

cURL · Petición sin credencial
curl "$CLOBEPAY_API_BASE/me"

Respuesta esperada: HTTP 401

Qué hacer con cada código

Códigos HTTP y acción recomendada
HTTPSignificadoAcción
400Petición inválida (validación, falta Idempotency-Key, credenciales ambiguas)Corrige la petición. No reintentes igual.
401Credencial ausente, inválida, revocada, expirada o de otro entornoRevisa la llave. No reintentes.
403Sin scope o comercio no operativoRevisa permisos o el estado del comercio.
404No existe o pertenece a otro comercioRevisa el identificador.
409Conflicto de estado (verificación no aprobada, petición idempotente en curso)Corrige el estado; si es idempotency_request_in_progress, reintenta.
422Regla de negocio (importe, Idempotency-Key reutilizada, URL no permitida)Corrige el cuerpo.
429Límite de peticionesEspera lo que indique Retry-After y reintenta.
5xxError transitorioReintenta 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.