En esta página
Manejo de Errores
Aprende a manejar los errores de la API de forma efectiva y proporcionar una buena experiencia a tus usuarios.
Formato de errores
Cuando ocurre un error, la API retorna una respuesta JSON con la siguiente estructura:
{
"success": false,
"statusCode": 400,
"message": "Texto del error",
"error": {
"code": "CODIGO_DEL_ERROR",
"message": "Texto del error"
},
"timestamp": "2026-10-30T16:57:11.300Z",
"path": "/api/v1/collect"
}
| Campo | Tipo | Descripción |
|---|---|---|
success |
boolean | Siempre false en errores |
statusCode |
number | El código HTTP de la respuesta. Es el dato principal para decidir qué hacer |
message |
string | Resumen del error |
error |
object o null | Detalle del error. En un error interno (500) llega en null |
error.code |
string | Código del error. Solo está presente en los errores de la tabla Códigos de error |
error.message |
string o lista de strings | Texto del error. En un error de validación es una lista con un texto por campo |
timestamp |
string | Fecha y hora del error (ISO 8601, UTC) |
path |
string | La ruta que pediste |
error.code. Los errores 401, los 400 de validación, los 404 y los 409 al cancelar un cobro solo traen statusCode y message. Otros 400, 403 y 409 sí traen error.code. Decide primero por statusCode y usa error.code solo cuando exista.
Códigos HTTP
La API usa códigos de estado HTTP estándar:
| Código | Significado | Cuándo ocurre |
|---|---|---|
200 |
OK | Solicitud exitosa (GET) |
201 |
Created | Recurso creado exitosamente (POST) |
400 |
Bad Request | Parámetros inválidos o faltantes, o una regla del cobro no se cumple |
401 |
Unauthorized | Credenciales inválidas o faltantes |
403 |
Forbidden | Tu llave no tiene el permiso, tu negocio no completó la vinculación (KYB) o la función no está activa para tu cuenta |
404 |
Not Found | Orden no encontrada |
409 |
Conflict | La orden no admite la operación en su estado actual (por ejemplo, cancelar dos veces), o la Idempotency-Key o la reference ya se usaron |
429 |
Too Many Requests | Límite de solicitudes excedido |
500 |
Internal Server Error | Error interno del servidor |
503 |
Service Unavailable | Una función o una tasa no está disponible en este momento |
Códigos de error
Estos son los errores con código que pueden devolver las rutas de esta documentación. Para el 429, el código está un nivel más adentro, en error.error.code. Para los demás, está en error.code. La lista puede crecer: si recibes un código que no está aquí, decide por statusCode.
| Código | HTTP | Dónde está el código |
|---|---|---|
COLLECT_AMOUNT_BELOW_MINIMUM | 400 | error.code |
USD_PRICE_WITH_AMOUNT | 400 | error.code |
USD_PRICE_INCOMPLETE | 400 | error.code |
USD_PRICE_CURRENCY_INVALID | 400 | error.code |
USD_PRICE_CURRENCY_NOT_COP | 400 | error.code |
USD_PRICE_EXPIRATION_TOO_LONG | 400 | error.code |
INVALID_CUSTOMER_DOCUMENT | 400 | error.code |
COLLECT_METADATA_RESERVED_KEY | 400 | error.code |
IDEMPOTENCY_KEY_REQUIRED | 400 | error.code |
FEE_MODE_UNAVAILABLE | 400 | error.code |
PAYER_DATA_REQUIRED | 400 | error.code |
PAYOUT_METHOD_NOT_AVAILABLE | 400 | error.code |
PAYOUT_SOURCE_MISMATCH | 400 | error.code |
KYB_REQUIRED | 403 | error.code |
FEATURE_DISABLED | 403 | error.code |
BRANCH_FORBIDDEN | 403 | error.code |
OUTFLOW_ON_HOLD | 403 | error.code |
IDEMPOTENCY_KEY_REUSED | 409 | error.code |
IDEMPOTENCY_BRANCH_MISMATCH | 409 | error.code |
REFERENCE_ALREADY_EXISTS | 409 | error.code |
MERCHANT_RATE_LIMIT_EXCEEDED | 429 | error.error.code |
RATE_UNAVAILABLE | 503 | error.code |
Las rutas POST /api/v1/collect/{id}/pay y GET /api/v1/collect/{id}/methods tienen además un límite por IP con su propio código. Consulta Límite por IP (429).
Errores de Autenticación (401)
Los errores 401 no traen error.code. Se distinguen por message:
message |
Descripción | Solución |
|---|---|---|
API Key and Secret are required |
Faltan los headers X-Api-Key o X-Api-Secret | Incluye ambos headers en la solicitud |
Invalid API credentials |
API Key o Secret inválidos, o la llave está revocada | Verifica que las credenciales sean correctas |
Merchant account is not active |
La cuenta del comercio no está activa | Contacta a soporte para verificar el estado de tu cuenta |
Ejemplo
Respuesta real de la API a una solicitud sin llave:
{
"success": false,
"statusCode": 401,
"message": "API Key and Secret are required",
"error": {
"message": "API Key and Secret are required",
"error": "Unauthorized",
"statusCode": 401
},
"timestamp": "2026-10-30T16:57:11.300Z",
"path": "/api/v1/collect"
}
Errores de Permisos (403)
| Error | Descripción | Solución |
|---|---|---|
KYB_REQUIRED en error.code |
Tu negocio no completó la vinculación (KYB) y la operación la exige | Completa la vinculación de tu empresa en el panel de negocios |
message: Esta API key no tiene el permiso … (sin error.code) |
Tu llave no tiene el permiso que la ruta exige | Agrega el permiso a la llave en el panel de negocios, o usa otra llave |
BRANCH_FORBIDDEN en error.code |
Tu llave está atada a una sede y enviaste otro branchId al crear un cobro |
No envíes branchId, o envía el de la sede de la llave |
OUTFLOW_ON_HOLD en error.code |
Las salidas de dinero de tu cuenta están en revisión. Aplica a POST /api/v1/payout |
Contacta a soporte |
Ejemplo
{
"success": false,
"statusCode": 403,
"message": "Completa la vinculación KYB de tu negocio para crear cobros nuevos",
"error": {
"code": "KYB_REQUIRED",
"message": "Completa la vinculación KYB de tu negocio para crear cobros nuevos"
},
"timestamp": "2026-10-30T16:57:11.300Z",
"path": "/api/v1/collect"
}
Errores de Validación (400)
Un 400 llega de dos formas:
- Validación de campos. No trae
error.code. El campoerror.messagees una lista con un texto por cada campo inválido. - Reglas del cobro. Traen un código en
error.code(tabla de abajo).
| Código | Descripción | Solución |
|---|---|---|
COLLECT_AMOUNT_BELOW_MINIMUM |
El monto en COP es menor al mínimo de un cobro | Envía un monto mayor o igual a 5.000 COP |
USD_PRICE_WITH_AMOUNT |
Enviaste amount y priceAmount en la misma solicitud |
Envía amount o el par priceCurrency + priceAmount, no los dos |
USD_PRICE_INCOMPLETE |
Falta priceCurrency o priceAmount |
Envía los dos campos juntos |
USD_PRICE_CURRENCY_INVALID |
priceCurrency distinto de USD |
Usa "USD", el único valor admitido |
USD_PRICE_CURRENCY_NOT_COP |
Con precio en USD, currency es distinta de COP |
Envía currency: "COP" o no envíes currency |
USD_PRICE_EXPIRATION_TOO_LONG |
Con precio en USD, expirationMinutes es mayor que 1440 (24 h) |
Usa 1440 minutos o menos |
INVALID_CUSTOMER_DOCUMENT |
El documento del cliente (customerDocType + customerDocNumber) no es válido |
Corrige el tipo o el número de documento. error.message dice qué falla |
COLLECT_METADATA_RESERVED_KEY |
metadata usa una clave reservada |
Cambia el nombre de las claves que nombra error.message |
IDEMPOTENCY_KEY_REQUIRED |
Falta la Idempotency-Key y la API la exige |
Envía el header Idempotency-Key o el campo idempotencyKey |
FEE_MODE_UNAVAILABLE |
Enviaste feeMode: "MERCHANT_PAYS" y esa opción no está disponible en este momento |
No envíes feeMode, o envía CUSTOMER_PAYS |
PAYER_DATA_REQUIRED |
Cobro directo (POST /api/v1/collect/{id}/pay): faltan datos del pagador. error.missingFields lista los campos que faltan (fullName, email, phone, docType, docNumber y bank en PSE). No se crea ningún cargo |
Pide esos datos al pagador y vuelve a llamar /pay con los campos en fields |
Ejemplo: validación de campos
Ojo: aquí error.message es una lista. El texto de cada elemento depende del campo.
{
"success": false,
"statusCode": 400,
"message": "Bad Request Exception",
"error": {
"message": [
"customerEmail must be an email",
"reference must be shorter than or equal to 100 characters"
],
"error": "Bad Request",
"statusCode": 400
},
"timestamp": "2026-10-30T16:57:11.300Z",
"path": "/api/v1/collect"
}
Ejemplo: monto bajo el mínimo
{
"success": false,
"statusCode": 400,
"message": "El monto mínimo de un cobro es $5.000 COP",
"error": {
"code": "COLLECT_AMOUNT_BELOW_MINIMUM",
"message": "El monto mínimo de un cobro es $5.000 COP"
},
"timestamp": "2026-10-30T16:57:11.300Z",
"path": "/api/v1/collect"
}
Errores de Orden (404, 409)
Estos errores no traen error.code. Se distinguen por statusCode y message:
| HTTP | message |
Descripción |
|---|---|---|
| 404 | Collect order not found |
La orden no existe o no pertenece a tu cuenta |
| 409 | El cobro ya terminó (…) y no se puede cancelar. |
Pediste cancelar una orden que ya está en un estado final, por ejemplo una orden ya cancelada |
| 409 | El cobro ya tiene un pago en curso y no se puede cancelar. |
El cliente ya empezó a pagar la orden |
| 409 | El cobro cambió de estado mientras se cancelaba; consulta su estado. |
Un pago cambió la orden mientras la cancelabas. Consulta la orden antes de reintentar |
Ejemplo
{
"success": false,
"statusCode": 404,
"message": "Collect order not found",
"error": {
"message": "Collect order not found",
"error": "Not Found",
"statusCode": 404
},
"timestamp": "2026-10-30T16:57:11.300Z",
"path": "/api/v1/collect/clxyz123abc456def"
}
Conflictos al crear un cobro (409)
Al crear un cobro con POST /api/v1/collect, estos 409 sí traen error.code:
| Código | Descripción | Solución |
|---|---|---|
IDEMPOTENCY_KEY_REUSED |
Usaste la misma Idempotency-Key con otro cuerpo |
Usa una clave nueva para un cobro distinto |
IDEMPOTENCY_BRANCH_MISMATCH |
La Idempotency-Key ya se usó para un cobro de otra sede |
Usa una clave nueva para esta sede |
REFERENCE_ALREADY_EXISTS |
Ya hay un cobro vivo o pagado con la misma reference |
Usa otra reference, o consulta el cobro que ya existe |
Ejemplo
{
"success": false,
"statusCode": 409,
"message": "Esta Idempotency-Key ya se usó para un cobro con otro cuerpo.",
"error": {
"code": "IDEMPOTENCY_KEY_REUSED",
"message": "Esta Idempotency-Key ya se usó para un cobro con otro cuerpo."
},
"timestamp": "2026-10-30T16:57:11.300Z",
"path": "/api/v1/collect"
}
Errores del precio en USD (403, 503)
| Código | HTTP | Descripción | Solución |
|---|---|---|---|
RATE_UNAVAILABLE |
503 | No hay una tasa USD/COP vigente para convertir el precio | Reintenta más tarde o crea el cobro con amount en COP |
FEATURE_DISABLED |
403 | Los cobros con precio en USD no están disponibles para tu cuenta | Crea el cobro con amount en COP o contacta a soporte |
Errores al crear un cobro (403)
| Código | HTTP | Descripción | Solución |
|---|---|---|---|
KYC_OR_KYB_REQUIRED |
403 | El comercio no tiene KYB aprobado ni KYC aprobado del dueño | Verifica tu negocio en el panel, sección Verificación |
MERCHANT_SUSPENDED |
403 | El comercio está suspendido | No reintentes. Contacta a soporte |
FEATURE_DISABLED |
403 | Al registrar el webhook por API: el webhook por llave no está habilitado para tu comercio | Configura el webhook general del comercio en el panel, en Integraciones → Webhooks («Webhook general»), y copia ahí la «Clave del webhook» como IIONPAY_WEBHOOK_SECRET |
API_KEY_PERMISSION_DENIED |
403 | Al registrar el webhook por API: la llave no tiene el permiso collect:webhook |
Crea la llave desde la tarjeta «Deja que tu agente integre iion pay» |
WEBHOOK_TEST_RATE_LIMITED |
429 | Más de 5 avisos de prueba por minuto | Espera un minuto y vuelve a probar |
Errores de Rate Limit (429)
Cada llave API tiene un límite de 120 solicitudes por minuto. Si lo excedes, la API responde 429 y bloquea la llave durante 60 segundos. En este error, el código está en error.error.code:
{
"success": false,
"statusCode": 429,
"message": "Http Exception",
"error": {
"success": false,
"data": null,
"error": {
"code": "MERCHANT_RATE_LIMIT_EXCEEDED",
"message": "Has superado el límite de 120 solicitudes por minuto. Reintenta en 42 segundos.",
"details": {
"limit": 120,
"remaining": 0,
"resetTime": "2024-01-15T12:01:00.000Z",
"retryAfter": 42
}
}
},
"timestamp": "2024-01-15T12:00:18.000Z",
"path": "/api/v1/collect"
}
La respuesta incluye estos headers. Espera los segundos de Retry-After antes de reintentar:
Retry-After: 42
X-RateLimit-Merchant-Limit: 120
X-RateLimit-Merchant-Remaining: 0
X-RateLimit-Merchant-Reset: 2024-01-15T12:01:00.000Z
Límite por IP (429)
Las rutas POST /api/v1/collect/{id}/pay y GET /api/v1/collect/{id}/methods tienen un segundo límite, por IP de origen. Es de 500 solicitudes por minuto. Si lo excedes, la API responde 429 y bloquea la IP durante 10 minutos.
Este 429 trae un código distinto: RATE_LIMIT_EXCEEDED, también en error.error.code. El límite de tu llave sigue activo en estas rutas: puedes recibir cualquiera de los dos 429. Las demás rutas solo usan MERCHANT_RATE_LIMIT_EXCEEDED.
{
"success": false,
"statusCode": 429,
"message": "Http Exception",
"error": {
"success": false,
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "Too many requests from this IP. You have been temporarily blocked until 2026-10-30T17:07:11.000Z.",
"details": {
"limit": 500,
"remaining": 0,
"resetTime": "2026-10-30T17:07:11.000Z",
"blocked": true,
"retryAfter": 600
}
}
},
"timestamp": "2026-10-30T16:57:11.300Z",
"path": "/api/v1/collect/clxyz123abc456def/pay"
}
Estas dos rutas envían X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset en cada respuesta. El 429 agrega Retry-After y, con la IP bloqueada, X-RateLimit-Blocked-Until. En el primer 429, Retry-After puede ser menor que el bloqueo: no reintentes antes de X-RateLimit-Blocked-Until.
Retry-After: 600
X-RateLimit-Limit: 500
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 2026-10-30T17:07:11.000Z
X-RateLimit-Blocked-Until: 2026-10-30T17:07:11.000Z
Manejo de Errores en tu Código
Decide por statusCode. Lee el código solo cuando exista: en error.code, o en error.error.code para el 429. En un 400 de validación, error.message es una lista.
// Saca el detalle del error: el 429 lo trae un nivel más adentro.
function errorDetail(data) {
const inner = data.error && typeof data.error.error === 'object' ? data.error.error : data.error;
const message = Array.isArray(inner?.message) ? inner.message.join('; ') : inner?.message ?? data.message;
return { code: inner?.code ?? null, message, details: inner?.details ?? null };
}
async function createCollectOrder(orderData, attempt = 0) {
const response = await fetch('https://api.prod.iionpay.com/api/v1/collect', {
method: 'POST',
headers: {
'X-Api-Key': process.env.IION_API_KEY,
'X-Api-Secret': process.env.IION_API_SECRET,
'Content-Type': 'application/json',
},
body: JSON.stringify(orderData),
});
const data = await response.json();
if (data.success) return data.data;
const { code, message, details } = errorDetail(data);
switch (data.statusCode) {
case 401:
// Sin error.code: el motivo está en message.
throw new Error(`Credenciales rechazadas: ${message}`);
case 429:
// code === 'MERCHANT_RATE_LIMIT_EXCEEDED'
if (attempt < 3) {
const retryAfter = Number(response.headers.get('Retry-After')) || details?.retryAfter || 60;
await new Promise((r) => setTimeout(r, retryAfter * 1000));
return createCollectOrder(orderData, attempt + 1);
}
throw new Error(message);
default: {
// 400, 403, 404, 409, 500, 503: code puede ser null.
const error = new Error(message);
error.statusCode = data.statusCode;
error.code = code;
throw error;
}
}
}
import os
import time
import requests
def error_detail(data):
"""Saca el detalle del error: el 429 lo trae un nivel más adentro."""
err = data.get('error') or {}
inner = err['error'] if isinstance(err.get('error'), dict) else err
message = inner.get('message') or data.get('message')
if isinstance(message, list):
message = '; '.join(message)
return inner.get('code'), message, inner.get('details') or {}
def create_collect_order(order_data, attempt=0):
response = requests.post(
'https://api.prod.iionpay.com/api/v1/collect',
headers={
'X-Api-Key': os.environ['IION_API_KEY'],
'X-Api-Secret': os.environ['IION_API_SECRET'],
'Content-Type': 'application/json',
},
json=order_data,
timeout=30,
)
data = response.json()
if data.get('success'):
return data['data']
status = data['statusCode']
code, message, details = error_detail(data)
if status == 401:
# Sin código: el motivo está en message.
raise Exception(f'Credenciales rechazadas: {message}')
if status == 429 and attempt < 3:
# code == 'MERCHANT_RATE_LIMIT_EXCEEDED'
retry_after = int(response.headers.get('Retry-After') or details.get('retryAfter', 60))
time.sleep(retry_after)
return create_collect_order(order_data, attempt + 1)
# 400, 403, 404, 409, 500, 503: code puede ser None.
raise Exception(f'{status} {code or ""} {message}'.strip())
Mensajes para el Usuario
Muestra mensajes amigables a tus usuarios según el tipo de error:
| Tipo de Error | Mensaje Sugerido |
|---|---|
| Validación (400) | "Por favor verifica los datos ingresados" |
| No encontrado (404) | "La orden de pago no existe o ya expiró" |
| Rate limit (429) | "Demasiados intentos. Espera un momento" |
| Error servidor (500) | "Error temporal. Intenta de nuevo en unos minutos" |