Ir al contenido

↑↓ navegar ↵ abrir Ctrl↵ nueva pestaña esc cerrar

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

CódigoSignificado
200Éxito con cuerpo
201Recurso creado
204Éxito sin cuerpo (ej.: Eliminar merchant)
CódigoSignificado
400El cuerpo no es un JSON válido (INVALID_JSON)
401Credenciales ausentes o inválidas
403Empresa bloqueada, registro de la empresa todavía no aprobado (KYB_NOT_APPROVED), o producto necesario no activo (PRODUCT_NOT_ACTIVE)
404Recurso no encontrado
405Operación no permitida (TRANSACTION_DELETE_NOT_ALLOWED)
409Conflicto (duplicado, actualización de recurso inmutable)
413Cuerpo por encima del tamaño máximo (PAYLOAD_TOO_LARGE)
422Error de validación
429Demasiadas solicitudes (rate limit)
CódigoSignificado
500Error interno (INTERNAL_ERROR), se recomienda reintentar
503No disponible temporalmente (SERVICE_UNAVAILABLE, CAPTURE_TEMPORARILY_UNAVAILABLE), con Retry-After

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.

Algunos errores traen también params y details, solo cuando existen:

{
"error": {
"code": "FIELD_TOO_LONG",
"message": "name must be at most 255 characters",
"params": { "field": "name", "max": 255 }
}
}
  • params: los datos del error, como el campo (field), el límite (max) o el id del recurso en conflicto (merchant_id, enrollment_id).
  • details: en el lote todo o nada rechazado (ENROLLMENT_BATCH_INVALID), la lista errors con index, code, message y params de cada ítem rechazado.

Si lees solo code y message, no necesitas cambiar nada.

CódigoHTTPUso
INVALID_JSON400El cuerpo no es un JSON válido
UNAUTHORIZED401Credenciales ausentes o inválidas
COMPANY_BLOCKED403Empresa bloqueada
PRODUCT_NOT_ACTIVE403Creación de transacción sin Prevención ni Disputa activa (ver Quién envía transacciones), o pedido de enrollment de un producto que tu empresa no tiene activo (params.product)
VALIDATION_ERROR422Uno o más campos inválidos
NOT_FOUND404La dirección no existe en la API (error de tipeo en la ruta, barra final de más)
TRANSACTION_NOT_FOUND404Transacción inexistente
TRANSACTION_DUPLICATE409external_source + external_id ya registrado
TRANSACTION_IMMUTABLE409Transacción ya utilizada, no se puede actualizar
TRANSACTION_DELETE_NOT_ALLOWED405Las transacciones no se pueden eliminar (ver Eliminar transacción)
MERCHANT_NOT_FOUND404Merchant inexistente
ALERT_NOT_FOUND404Alerta inexistente
ALERT_INVALID_STATUS422Estado inválido, o transición no permitida (plazo, vencimiento o estado ya definitivo)
PAYLOAD_TOO_LARGE413Cuerpo por encima del límite: 1 MB por solicitud, 5 MB en el envío por lotes y en el lote de merchants, 2 MB en el lote de enrollments
RATE_LIMIT_EXCEEDED429Límite de solicitudes superado (ver abajo)
ORIGIN_NOT_ALLOWED403Evento de captura que viene de un sitio que no está entre los sitios en los que vale el token (ver En qué sitio vale el token)
TOO_MANY_PENDING_EVENTS429Demasiados eventos de captura esperando a que aparezca la transacción (ver Límite de llamadas)
CAPTURE_TEMPORARILY_UNAVAILABLE503Captura temporalmente no disponible. Reenvía el evento después del Retry-After, con el mismo event_id
SERVICE_UNAVAILABLE503No disponible temporalmente en merchants, enrollments y uso. Repetir es seguro: la llamada repetida no duplica nada. Espera el Retry-After
INTERNAL_ERROR500Error inesperado en el servidor

Códigos de Merchants, Enrollments y Uso por merchant.

CódigoHTTPUso
KYB_NOT_APPROVED403El registro de tu empresa todavía no fue aprobado: las escrituras quedan bloqueadas hasta la aprobación
COMPANY_NOT_ACTIVE403La empresa no está activa
FIELD_REQUIRED422Falta un campo obligatorio (params.field)
FIELD_TOO_LONG422Campo por encima del límite (params.field, params.max)
FIELD_INVALID422Valor inválido en el campo (params.field)
FIELD_INVALID_OPTION422Valor fuera de la lista aceptada (params.field, params.options)
BATCH_IN_PROGRESS429Otro lote de tu empresa (del mismo tipo) todavía se está guardando. Espera el Retry-After
MERCHANT_DUPLICATE409Otro merchant tuyo ya tiene el nombre (params.merchant_id)
MERCHANT_REF_CONFLICT409merchant_ref distinto del guardado solo en mayúsculas o acentos
MERCHANT_REF_TAKEN409Otro merchant tuyo ya usa el merchant_ref
MERCHANT_REF_IMMUTABLE409El merchant_ref no se cambia después de guardado
MERCHANT_HAS_HISTORY409Un merchant con datos vinculados no se elimina: guarda status: "inactive" y solicita la desactivación de los enrollments
MERCHANT_REF_DUPLICATE_IN_BATCH422merchant_ref repetido en el mismo lote
MERCHANT_NAME_DUPLICATE_IN_BATCH422name repetido en el mismo lote
ENROLLMENT_NOT_FOUND404Enrollment inexistente
ENROLLMENT_DUPLICATE409Identificador ya en uso en la plataforma
ENROLLMENT_PREVIOUSLY_REJECTED409Identificador rechazado antes; envía retry_rejected: true para solicitarlo de nuevo
ENROLLMENT_DUPLICATE_IN_BATCH422Identificador repetido en el mismo lote
ENROLLMENT_BATCH_INVALID422Lote todo o nada con un ítem rechazado; no se guardó nada (details.errors)
ENROLLMENT_NO_PRODUCT422Ningún producto solicitado
ENROLLMENT_PENDING_LIMIT42220.000 enrollments esperando aprobación en tu empresa
ENROLLMENT_NOTHING_TO_DEACTIVATE422Ningún producto activo para desactivar
DESCRIPTOR_LOOKS_LIKE_BIN_CAID422El descriptor parece un BIN/CAID: solicítalo como bin_caid
DESCRIPTOR_PREFIX_TOO_SHORT422“Empieza con” con menos de 5 caracteres
BIN_INVALID422bin fuera de 6 a 10 dígitos
PROVIDER_UNAVAILABLE422El producto no acepta ese tipo de enrollment
MERCHANT_INCOMPLETE_FOR_PREVENTION422Faltan datos de registro del merchant para la Prevención (params.fields)
USAGE_CYCLE_NOT_FOUND404Ningún ciclo de facturación cerrado empieza en el mes pedido

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 son las rutas de captura desde el navegador, que no cuentan en los 100: el envío de eventos tiene su propio tope de 120 por minuto y la configuración del snippet, de 300 por minuto, las dos contadas por IP y token. El script rapid.js del snippet también queda fuera, con su propio tope de 300 por minuto por IP.

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.

Además de los 100 por IP, algunas rutas tienen límite por empresa, contado por la credencial:

RutasLímite
Escrituras de merchants y enrollments (POST, PATCH, DELETE; cada lote cuenta como una)60 por minuto
Uso por merchant10 por minuto
Lotes de merchants y de enrollments1 de cada tipo en curso (429 BATCH_IN_PROGRESS, Retry-After: 5)

Al pasar el límite por minuto, la respuesta es el mismo 429 RATE_LIMIT_EXCEEDED, con Retry-After.

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.

Los errores 5xx suelen ser transitorios. Reintenta aumentando el intervalo entre intentos. Cuando la respuesta trae Retry-After (los 503 lo traen), espera ese tiempo. En merchants y enrollments, el 503 SERVICE_UNAVAILABLE puede llegar después de que la escritura se guardó: repetir la misma llamada es seguro, porque no duplica nada (vuelve unchanged o existing). No reintentes los demás 4xx: indican un error de tu lado y volverán a fallar. La excepción es el 429: espera el tiempo del Retry-After y vuelve a intentar (ver Rate limit).