Errores

Toda respuesta de error tiene la misma forma:

{ "error": {
    "type": "invalid_request_error", "code": "limit_exceeded",
    "message": "Supera el límite por operación de pago móvil",
    "request_id": "req_8a0312ba896772bc441134cd",
    "meta": { "limit": "per_tx_max", "max": "10000000", "scope": "platform" } } }

Campo	Qué es
`code`	Código estable. Programa contra esto
`type`	Familia del error: te dice si tiene sentido reintentar
`message`	Texto legible. Puede cambiar o traducirse: no lo parsees
`request_id`	También viaja en la cabecera `x-request-id`. Inclúyelo al abrir un ticket
`meta`	Contexto estructurado cuando lo hay: qué límite se superó, qué campo es inválido, cuánto saldo había. Ausente en errores internos

Tu switch sobre error.code necesita un default para códigos desconocidos.

Familias (`type`)

`type`	HTTP	Significa	¿Reintentar?
`invalid_request_error`	400 · 404 · 409 · 422	Algo de la petición está mal	No sin corregir
`authentication_error`	401 · 403	Credenciales o permisos	No
`rate_limit_error`	429	Vas demasiado rápido	Sí, más despacio
`upstream_error`	502 · 503	Fallo de una red de pago	Sí, con la misma `Idempotency-Key`
`api_error`	≥ 500	Fallo nuestro	Sí

Catálogo

Autenticación y permisos

Código	HTTP	Qué hacer
`api_key_missing`	401	Falta el header `x-api-key`
`api_key_invalid`	401	Revisar credenciales
`api_key_revoked`	401	Esa clave se revocó
`api_key_expired`	401	Pedir una nueva
`tenant_suspended`	403	Contactar a soporte
`insufficient_scope`	403	Usar una clave con el scope de `meta.required`

Petición

Código	HTTP	Qué hacer
`validation_failed`	400	Corregir el cuerpo o la query. El `message` dice qué campo; a veces también `meta.field`
`api_version_unsupported`	400	`BC-Version` con una versión que no existe, o `2026-10-22` en producción. Usa `2026-11-03` (migrar a los nombres en inglés)
`invalid_amount`	400	Monto ≤ 0, fuera de rango, o tan pequeño que la comisión se lo comería
`unsupported_asset`	400	Activo o par no soportado

Idempotencia

Código	HTTP	Qué hacer
`idempotency_key_reused`	409	Clave nueva: el cuerpo cambió
`idempotency_request_in_flight`	409	La original sigue en curso; reintentar en segundos

Cotización

Código	HTTP	Qué hacer
`quote_not_found`	404	No existe, o es de otro programa
`quote_expired`	422	Pedir una cotización nueva
`quote_already_consumed`	409	Esa cotización ya la usó otra dispersión
`sell_rate_missing`	422	Vendes con tu tasa y no hay una fijada para ese activo: fíjala
`sell_rate_managed_by_platform`	403	Acordaste que tu tasa de venta la fija Bolívar Connect al aceptar cada fondeo: no se cambia por API (vender con tu tasa)

Beneficiario

Código	HTTP	Qué hacer
`beneficiary_not_found`	404	El `beneficiaryId` no es tuyo o no existe
`beneficiary_blocked`	422	Está bloqueado: ni se lee ni se le dispersa
`beneficiary_instrument_missing`	422	Sin teléfono para pago móvil, o sin cuenta para transferencia. `meta` trae `beneficiaryId` e `instrument`

Dinero y límites

Código	HTTP	Qué hacer
`insufficient_tenant_funds`	422	Tu saldo no alcanza. Sólo si operas prefondeado
`credit_limit_exceeded`	422	Agotaste la línea del cierre diario
`limit_exceeded`	422	`meta` dice qué límite (`per_tx_max`, `daily_max`, `monthly_max`, `daily_count_max`), el tope y el consumo
`invalid_state_transition`	409	La operación no aplica al estado actual del pago

Comprobante

Código	HTTP	Qué hacer
`receipt_not_available`	409	El pago no llegó a `settled`: no hay comprobante (compartir el comprobante)
`receipt_link_limit_reached`	409	El pago ya tiene 20 enlaces vivos: revoca alguno
`receipt_not_found`	404	El enlace no existe, venció, se revocó o es de otro pago

Recursos

payment_not_found, quote_not_found, beneficiary_not_found y event_not_found → 404, igual que un recurso de otro programa.

Redes de pago y plataforma

Código	HTTP	Qué hacer
`no_route_available`	503	No hay red de pago para ese banco/instrumento ahora mismo. Reintentar más tarde
`upstream_error`	502	Fallo de la red de pago o del emisor. Reintentar con la misma `Idempotency-Key`
`rate_limited`	429	Bajar el ritmo. Respetar `Retry-After`
`internal_error`	500	Fallo nuestro. Reintentable; manda el `request_id` si persiste

Un error que no encaje en los códigos anteriores llega con un código genérico por familia: not_found (404), conflict (409), unprocessable (422) o invalid_request (400). Trátalos como el resto de su familia.

Los motivos de rechazo de la red de pago no son `error.code`

{ "id": "89920401-26da-4f69-b57d-bc20e0366ce2", "status": "failed",
  "reason": "beneficiary_missing_phone",
  "asset": "BS", "amount": "5000000", "feeAmount": "0" }

`reason`	Qué pasó
`beneficiary_missing_phone`	Falta el móvil del beneficiario en pago móvil. En transferencia es opcional
`beneficiary_missing_account`	Falta el número de cuenta para transferencia
`beneficiary_mismatch`	Nombre o cédula no coinciden con el titular de esa cuenta o teléfono
`invalid_destination_account`	La cuenta destino no existe o está mal formada
`sender_required`	No había remitente por ninguno de los tres caminos
`sender_phone_unsupported`	Ninguna red de pago disponible admitía el teléfono internacional (E.164) del remitente
`amount_below_minimum`	Por debajo del piso de la red de pago
`amount_above_limit`	Por encima del techo de la red de pago
`amount_not_positive`	Importe ≤ 0
`amount_precision_loss`	El importe no se puede representar sin perder céntimos
`bank_unreachable`	Esa red de pago no cubre el banco destino
`instrument_unsupported`	Esa red de pago no ofrece ese instrumento
`payout_insufficient_balance`	Sin saldo para el pago y la comisión de la red de pago en la cuenta que dispersa
`payout_balance_unavailable`	No se pudo leer el saldo de la cuenta que dispersa: no se envió nada
`payout_rejected`	Rechazo genérico de la red de pago
`payout_timeout`	No sabemos si pagó → el pago queda en `unknown`, no en `failed`
`no_route`	No hay red de pago disponible para esa combinación

El mismo valor queda en status_reason del pago y en el reason de la transición dentro de events[]. Qué hacer con cada uno: cuando algo falla.

Y un caso que no es un error

Un pago con status: "unknown" responde 200/201, no un error: la red de pago no confirmó, y el pago está en duda. Ver estados de un pago.