Códigos de respuesta
Referencia de los códigos HTTP usados en toda la API de Rapid.
Códigos de éxito
Sección titulada «Códigos de éxito»| Código | Significado |
|---|---|
| 200 | Éxito con cuerpo |
| 201 | Recurso creado |
| 204 | Éxito sin cuerpo (ej.: Eliminar merchant) |
Códigos de error del cliente
Sección titulada «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, registro de la empresa todavía no aprobado (KYB_NOT_APPROVED), o producto necesario no activo (PRODUCT_NOT_ACTIVE) |
| 404 | Recurso no encontrado |
| 405 | Operación no permitida (TRANSACTION_DELETE_NOT_ALLOWED) |
| 409 | Conflicto (duplicado, actualización de 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
Sección titulada «Códigos de error del servidor»| Código | Significado |
|---|---|
| 500 | Error interno (INTERNAL_ERROR), se recomienda reintentar |
| 503 | No disponible temporalmente (SERVICE_UNAVAILABLE, CAPTURE_TEMPORARILY_UNAVAILABLE), con Retry-After |
Formato del cuerpo de error
Sección titulada «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.
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 listaerrorsconindex,code,messageyparamsde cada ítem rechazado.
Si lees solo code y message, no necesitas cambiar nada.
Códigos semánticos más comunes
Sección titulada «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 |
PRODUCT_NOT_ACTIVE | 403 | Creació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_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 actualizar |
TRANSACTION_DELETE_NOT_ALLOWED | 405 | Las transacciones no se pueden eliminar (ver Eliminar transacción) |
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 y en el lote de merchants, 2 MB en el lote de enrollments |
RATE_LIMIT_EXCEEDED | 429 | Límite de solicitudes superado (ver abajo) |
ORIGIN_NOT_ALLOWED | 403 | Evento 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_EVENTS | 429 | Demasiados eventos de captura esperando a que aparezca la transacción (ver Límite de llamadas) |
CAPTURE_TEMPORARILY_UNAVAILABLE | 503 | Captura temporalmente no disponible. Reenvía el evento después del Retry-After, con el mismo event_id |
SERVICE_UNAVAILABLE | 503 | No disponible temporalmente en merchants, enrollments y uso. Repetir es seguro: la llamada repetida no duplica nada. Espera el Retry-After |
INTERNAL_ERROR | 500 | Error inesperado en el servidor |
Merchants, enrollments y uso
Sección titulada «Merchants, enrollments y uso»Códigos de Merchants, Enrollments y Uso por merchant.
| Código | HTTP | Uso |
|---|---|---|
KYB_NOT_APPROVED | 403 | El registro de tu empresa todavía no fue aprobado: las escrituras quedan bloqueadas hasta la aprobación |
COMPANY_NOT_ACTIVE | 403 | La empresa no está activa |
FIELD_REQUIRED | 422 | Falta un campo obligatorio (params.field) |
FIELD_TOO_LONG | 422 | Campo por encima del límite (params.field, params.max) |
FIELD_INVALID | 422 | Valor inválido en el campo (params.field) |
FIELD_INVALID_OPTION | 422 | Valor fuera de la lista aceptada (params.field, params.options) |
BATCH_IN_PROGRESS | 429 | Otro lote de tu empresa (del mismo tipo) todavía se está guardando. Espera el Retry-After |
MERCHANT_DUPLICATE | 409 | Otro merchant tuyo ya tiene el nombre (params.merchant_id) |
MERCHANT_REF_CONFLICT | 409 | merchant_ref distinto del guardado solo en mayúsculas o acentos |
MERCHANT_REF_TAKEN | 409 | Otro merchant tuyo ya usa el merchant_ref |
MERCHANT_REF_IMMUTABLE | 409 | El merchant_ref no se cambia después de guardado |
MERCHANT_HAS_HISTORY | 409 | Un merchant con datos vinculados no se elimina: guarda status: "inactive" y solicita la desactivación de los enrollments |
MERCHANT_REF_DUPLICATE_IN_BATCH | 422 | merchant_ref repetido en el mismo lote |
MERCHANT_NAME_DUPLICATE_IN_BATCH | 422 | name repetido en el mismo lote |
ENROLLMENT_NOT_FOUND | 404 | Enrollment inexistente |
ENROLLMENT_DUPLICATE | 409 | Identificador ya en uso en la plataforma |
ENROLLMENT_PREVIOUSLY_REJECTED | 409 | Identificador rechazado antes; envía retry_rejected: true para solicitarlo de nuevo |
ENROLLMENT_DUPLICATE_IN_BATCH | 422 | Identificador repetido en el mismo lote |
ENROLLMENT_BATCH_INVALID | 422 | Lote todo o nada con un ítem rechazado; no se guardó nada (details.errors) |
ENROLLMENT_NO_PRODUCT | 422 | Ningún producto solicitado |
ENROLLMENT_PENDING_LIMIT | 422 | 20.000 enrollments esperando aprobación en tu empresa |
ENROLLMENT_NOTHING_TO_DEACTIVATE | 422 | Ningún producto activo para desactivar |
DESCRIPTOR_LOOKS_LIKE_BIN_CAID | 422 | El descriptor parece un BIN/CAID: solicítalo como bin_caid |
DESCRIPTOR_PREFIX_TOO_SHORT | 422 | “Empieza con” con menos de 5 caracteres |
BIN_INVALID | 422 | bin fuera de 6 a 10 dígitos |
PROVIDER_UNAVAILABLE | 422 | El producto no acepta ese tipo de enrollment |
MERCHANT_INCOMPLETE_FOR_PREVENTION | 422 | Faltan datos de registro del merchant para la Prevención (params.fields) |
USAGE_CYCLE_NOT_FOUND | 404 | Ningún ciclo de facturación cerrado empieza en el mes pedido |
Rate limit
Sección titulada «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 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 RequestsRetry-After: 15X-RateLimit-Limit: 100X-RateLimit-Remaining: 0X-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.
Límites por empresa
Sección titulada «Límites por empresa»Además de los 100 por IP, algunas rutas tienen límite por empresa, contado por la credencial:
| Rutas | Límite |
|---|---|
Escrituras de merchants y enrollments (POST, PATCH, DELETE; cada lote cuenta como una) | 60 por minuto |
| Uso por merchant | 10 por minuto |
| Lotes de merchants y de enrollments | 1 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.
Reintentos en errores 5xx
Sección titulada «Reintentos en errores 5xx»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).