Skip to main content

​
Manejo de Errores

La API de ZenFlow usa códigos de estado HTTP estándar y retorna información detallada de errores en formato JSON.

​
Formato de Respuesta de Error

Todos los errores siguen esta estructura: 
{
  "success": false,
  "error": {
    "code": "codigo_error",
    "message": "Mensaje de error legible",
    "details": {} // Información adicional opcional
  }
}

​
Códigos de Estado HTTP

CódigoDescripciónCuándo Ocurre
400Bad RequestCuerpo de solicitud o parámetros inválidos
401UnauthorizedAPI key faltante o inválida
403ForbiddenKey válida pero permisos insuficientes
404Not FoundEl recurso no existe
409ConflictEl recurso ya existe
422UnprocessableValidación fallida
429Too Many RequestsLímite de tasa excedido
500Internal ErrorError del servidor

​
Códigos de Error Comunes

​
Errores de Autenticación

CódigoMensajeResolución
missing_api_keyAPI key es requeridaAgrega el header X-API-Key
invalid_api_keyAPI key es inválidaVerifica tu API key
expired_api_keyAPI key ha expiradoCrea una nueva API key
revoked_api_keyAPI key fue revocadaCrea una nueva API key
{
  "success": false,
  "error": {
    "code": "invalid_api_key",
    "message": "La API key proporcionada es inválida o ha sido revocada"
  }
}

​
Errores de Autorización

CódigoMensajeResolución
insufficient_scopeFalta scope requeridoUsa key con scopes apropiados
ip_not_allowedIP no está en whitelistAgrega tu IP a la whitelist
{
  "success": false,
  "error": {
    "code": "insufficient_scope",
    "message": "Esta API key no tiene el scope requerido: write:orders"
  }
}

​
Errores de Validación

CódigoMensajeResolución
validation_errorValor de campo inválidoRevisa el campo details
invalid_idFormato de ID incorrectoUsa el formato de ID correcto
missing_fieldCampo requerido faltanteIncluye los campos requeridos
{
  "success": false,
  "error": {
    "code": "validation_error",
    "message": "Datos de pedido inválidos",
    "details": [
      {
        "field": "assembly_date",
        "message": "Debe ser una fecha válida en formato YYYY-MM-DD"
      },
      {
        "field": "order_detail",
        "message": "Se requiere al menos un item"
      }
    ]
  }
}

​
Errores de Recurso

CódigoMensajeResolución
not_foundRecurso no encontradoVerifica el ID del recurso
already_existsRecurso ya existeUsa un identificador diferente
{
  "success": false,
  "error": {
    "code": "not_found",
    "message": "Pedido no encontrado"
  }
}

​
Límite de Tasa

{
  "success": false,
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Límite de tasa excedido. Intenta de nuevo en 30 segundos."
  }
}
Consulta Límites de Tasa para estrategias de manejo.

​
Manejando Errores

​
JavaScript/TypeScript

async function createOrder(orderData) {
  try {
    const response = await fetch("/api/v1/orders", {
      method: "POST",
      headers: {
        "X-API-Key": API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify(orderData),
    });

    const result = await response.json();

    if (!result.success) {
      switch (result.error.code) {
        case "validation_error":
          // Muestra errores de validación al usuario
          console.error("Validación fallida:", result.error.details);
          break;
        case "already_exists":
          // Maneja duplicado
          console.error("El pedido ya existe");
          break;
        case "rate_limit_exceeded":
          // Reintenta después de delay
          await delay(30000);
          return createOrder(orderData);
        default:
          console.error("Error de API:", result.error.message);
      }
      throw new Error(result.error.message);
    }

    return result.data;
  } catch (error) {
    if (error.name === "TypeError") {
      // Error de red
      console.error("Error de red");
    }
    throw error;
  }
}

​
Python

import requests

def create_order(order_data):
    try:
        response = requests.post(
            'https://api.zenflow.com.ar/api/v1/orders',
            headers={'X-API-Key': API_KEY},
            json=order_data
        )

        result = response.json()

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

            if code == 'validation_error':
                print(f"Validación fallida: {error.get('details')}")
            elif code == 'rate_limit_exceeded':
                time.sleep(30)
                return create_order(order_data)
            else:
                print(f"Error de API: {error.get('message')}")

            raise Exception(error.get('message'))

        return result.get('data')

    except requests.exceptions.RequestException as e:
        print(f"Error de red: {e}")
        raise

​
Mejores Prácticas

Verifica el Campo success

Siempre verifica el campo success en las respuestas

Registra Códigos de Error

Registra códigos de error para debugging y monitoreo

Maneja Reintentos

Implementa lógica de reintentos para errores transitorios

Mensajes al Usuario

Muestra mensajes amigables para errores de validación

​
Estrategia de Reintentos

Reintenta estos errores con backoff exponencial:
  • 429 Límite de tasa excedido
  • 500 Error interno del servidor
  • 503 Servicio no disponible
  • Timeouts de red
No reintentes estos errores:
  • 400 Bad request (corrige la solicitud primero)
  • 401 Unauthorized (corrige la autenticación)
  • 403 Forbidden (verifica permisos)
  • 404 Not found (el recurso no existe)

​
Obteniendo Ayuda

Si encuentras errores persistentes:
  1. Revisa el código y mensaje de error
  2. Revisa la documentación de la API
  3. Verifica el estado del servicio
  4. Contacta a [email protected] con:
    • Código y mensaje de error
    • Detalles de la solicitud (endpoint, método)
    • Timestamp del error