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
No todos los errores traen un código
Ojo: no todos los errores traen 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_MINIMUM400error.code
USD_PRICE_WITH_AMOUNT400error.code
USD_PRICE_INCOMPLETE400error.code
USD_PRICE_CURRENCY_INVALID400error.code
USD_PRICE_CURRENCY_NOT_COP400error.code
USD_PRICE_EXPIRATION_TOO_LONG400error.code
INVALID_CUSTOMER_DOCUMENT400error.code
COLLECT_METADATA_RESERVED_KEY400error.code
IDEMPOTENCY_KEY_REQUIRED400error.code
FEE_MODE_UNAVAILABLE400error.code
PAYER_DATA_REQUIRED400error.code
PAYOUT_METHOD_NOT_AVAILABLE400error.code
PAYOUT_SOURCE_MISMATCH400error.code
KYB_REQUIRED403error.code
FEATURE_DISABLED403error.code
BRANCH_FORBIDDEN403error.code
OUTFLOW_ON_HOLD403error.code
IDEMPOTENCY_KEY_REUSED409error.code
IDEMPOTENCY_BRANCH_MISMATCH409error.code
REFERENCE_ALREADY_EXISTS409error.code
MERCHANT_RATE_LIMIT_EXCEEDED429error.error.code
RATE_UNAVAILABLE503error.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 campo error.message es 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"
No expongas detalles técnicos
Nunca muestres códigos de error o detalles técnicos a los usuarios finales. Loguéalos internamente para debugging.