Códigos de respuesta

Referencia de los códigos HTTP usados en toda la API de Rapid.

Códigos de éxito

Código	Significado
200	Éxito con cuerpo
201	Recurso creado
204	Éxito sin cuerpo (ej.: DELETE)

Códigos de error del cliente

Código	Significado
400	El cuerpo no es un JSON válido (INVALID_JSON)
401	Credenciales ausentes o inválidas
403	Empresa bloqueada
404	Recurso no encontrado
409	Conflicto (duplicado, recurso inmutable)
413	Cuerpo por encima del tamaño máximo (PAYLOAD_TOO_LARGE)
422	Error de validación
429	Demasiadas solicitudes (rate limit)

Códigos de error del servidor

Código	Significado
500	Error interno (INTERNAL_ERROR), se recomienda reintentar

---

Formato del cuerpo de error

Toda respuesta de error tiene esta estructura:

{
  "error": {
    "code": "CODIGO_SEMANTICO",
    "message": "Descripción legible del error"
  }
}

El message viene en inglés y es para quien lee el log: el texto puede cambiar. Para decidir qué hacer en tu código, usa el code. Los endpoints que se mantienen del sistema anterior responden como antes.

Códigos semánticos más comunes

Código	HTTP	Uso
INVALID_JSON	400	El cuerpo no es un JSON válido
UNAUTHORIZED	401	Credenciales ausentes o inválidas
COMPANY_BLOCKED	403	Empresa bloqueada
VALIDATION_ERROR	422	Uno o más campos inválidos
NOT_FOUND	404	La dirección no existe en la API (error de tipeo en la ruta, barra final de más)
TRANSACTION_NOT_FOUND	404	Transacción inexistente
TRANSACTION_DUPLICATE	409	external_source + external_id ya registrado
TRANSACTION_IMMUTABLE	409	Transacción ya utilizada, no se puede modificar
MERCHANT_NOT_FOUND	404	Merchant inexistente
ALERT_NOT_FOUND	404	Alerta inexistente
ALERT_INVALID_STATUS	422	Estado inválido, o transición no permitida (plazo, vencimiento o estado ya definitivo)
PAYLOAD_TOO_LARGE	413	Cuerpo por encima del límite: 1 MB por solicitud, 5 MB en el envío por lotes
RATE_LIMIT_EXCEEDED	429	Límite de solicitudes superado (ver abajo)
INTERNAL_ERROR	500	Error inesperado en el servidor

Rate limit

Todas las rutas comparten un límite de 100 solicitudes por minuto por IP, incluidas las que responden 401 por credencial inválida. La excepción es el envío de eventos desde el navegador, que tiene su propio tope de 120 por minuto y no cuenta en los 100.

Al superarlo, la API devuelve:

HTTP/1.1 429 Too Many Requests
Retry-After: 15
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 15

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded, retry in 15 seconds"
  }
}

Usa el Retry-After. Indica, en segundos, cuánto falta para que la ventana se reinicie, y el mensaje repite el mismo número. Esperar exactamente eso es mejor que adivinar: una espera progresiva a ciegas puede reintentar antes de tiempo (y recibir otro 429) o esperar más de lo necesario.

Los headers X-RateLimit-* vienen en todas las respuestas, no solo en el 429, así que puedes adelantarte: cuando X-RateLimit-Remaining se acerque a cero, frena el envío en vez de esperar el error. Para volumen, prefiere el envío por lotes, que manda hasta 1000 transacciones en una solicitud y gasta una unidad del límite.

Reintentos en errores 5xx

Los errores 5xx suelen ser transitorios. Reintenta aumentando el intervalo entre intentos. Nunca reintentes 4xx: indican un error de tu lado y volverán a fallar.