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,
  "error": {
    "code": "ERROR_CODE",
    "message": "Descripción legible del error",
    "details": {}
  }
}

Códigos HTTP

La API usa códigos de estado HTTP estándar:

Errores de Autenticación (401)

Ejemplo

{
  "success": false,
  "error": {
    "code": "INVALID_CREDENTIALS",
    "message": "Invalid API credentials",
    "details": {}
  }
}

Errores de Validación (400)

Ejemplo

{
  "success": false,
  "error": {
    "code": "INVALID_AMOUNT",
    "message": "Amount must be at least 1000 COP",
    "details": {
      "field": "amount",
      "value": 500,
      "minimum": 1000
    }
  }
}

Errores de Orden (400, 404)

Ejemplo

{
  "success": false,
  "error": {
    "code": "ORDER_NOT_FOUND",
    "message": "Collect order not found",
    "details": {}
  }
}

Errores de Rate Limit (429)

Si excedes el límite de solicitudes, recibirás este error:

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Please try again later.",
    "details": {
      "retryAfter": 60
    }
  }
}

Los headers de respuesta incluyen información sobre el límite:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1705323600

Manejo de Errores en tu Código

Recomendamos implementar un manejo de errores robusto:

async function createCollectOrder(orderData) {
  try {
    const response = await fetch('https://api.prod.niiopay.com/api/v1/collect', {
      method: 'POST',
      headers: {
        'X-Api-Key': process.env.NIIO_API_KEY,
        'X-Api-Secret': process.env.NIIO_API_SECRET,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify(orderData),
    });

    const data = await response.json();

    if (!data.success) {
      // Manejar error según el código
      switch (data.error.code) {
        case 'INVALID_CREDENTIALS':
          console.error('Error de autenticación');
          throw new Error('Error de configuración');

        case 'RATE_LIMIT_EXCEEDED':
          // Esperar y reintentar
          const retryAfter = data.error.details?.retryAfter || 60;
          await new Promise(r => setTimeout(r, retryAfter * 1000));
          return createCollectOrder(orderData);

        default:
          throw new Error(data.error.message);
      }
    }

    return data.data;
  } catch (error) {
    console.error('Error al crear orden:', error);
    throw error;
  }
}

import requests
import time
import os

def create_collect_order(order_data):
    try:
        response = requests.post(
            'https://api.prod.niiopay.com/api/v1/collect',
            headers={
                'X-Api-Key': os.environ['NIIO_API_KEY'],
                'X-Api-Secret': os.environ['NIIO_API_SECRET'],
                'Content-Type': 'application/json',
            },
            json=order_data,
            timeout=30
        )

        data = response.json()

        if not data.get('success'):
            error_code = data.get('error', {}).get('code')

            if error_code == 'INVALID_CREDENTIALS':
                raise Exception('Error de configuración')

            elif error_code == 'RATE_LIMIT_EXCEEDED':
                retry_after = data['error'].get('details', {}).get('retryAfter', 60)
                time.sleep(retry_after)
                return create_collect_order(order_data)

            else:
                raise Exception(data['error']['message'])

        return data['data']

    except requests.exceptions.RequestException as e:
        print(f'Error de conexión: {e}')
        raise

Mensajes para el Usuario

Muestra mensajes amigables a tus usuarios según el tipo de error: