Manejo de errores

Formato de respuesta de error unificado

Todos los errores API devuelven un formato JSON unificado:

JSON

{
  "code": 2010,
  "status": "error",
  "message": "You don't have enough credit to create this task",
  "suggestion": "Please purchase more credit",
  "request_id": "req_abc123"
}

campo	Tipo	Descripción
code	entero	código de error
status	cadena	Resultado de la solicitud; `error` cuando la solicitud falla
message	cadena	Descripción del error
suggestion	cadena	Solución sugerida
request_id	cadena	Identificador de solicitud único para solución de problemas

Códigos de estado HTTP

Código de estado	Significado	Descripción
200	Éxito	La solicitud fue procesada exitosamente.
400	Parámetros no válidos	Faltan parámetros requeridos o están mal formados
401	No autenticado	El API Key falta o no es válido
403	Permisos insuficientes	No tienes permiso para acceder al recurso, o tus créditos son insuficientes
404	Recurso no encontrado	La tarea o recurso solicitado no existe
429	Demasiadas solicitudes	Se superó el límite de velocidad o el límite de simultaneidad. Reduzca la frecuencia de sus solicitudes o vuelva a intentarlo más tarde
500	error de servicio	Error interno del servidor. Vuelve a intentarlo más tarde

Referencia de código de error

Código de error	Significado	Manejo recomendado
1000	API Key no válido	Compruebe si el API Key es correcto o se ha eliminado
1001	No autorizado	Compruebe si el encabezado de la solicitud incluye `Authorization`
1007	Límite de velocidad excedido	Reduzca la frecuencia de solicitudes e implemente reintentos con retroceso exponencial
2000	Límite de simultaneidad excedido	Espere a que termine una tarea de la misma categoría antes de crear otras, o espere el tiempo que indique el encabezado de respuesta `Retry-After`. Consulte Límites de velocidad
2002	Parámetro de solicitud no admitido	Compruebe si los nombres y valores de los campos del cuerpo de la solicitud coinciden con la documentación
2003	Archivo de entrada vacío	Confirme que el archivo cargado no esté vacío y utilice un formato válido
2004	Tipo de archivo no compatible	Compruebe si el formato de archivo está en la lista admitida
2008	Violación de la política de contenido	Modifique el contenido de entrada para evitar palabras o imágenes prohibidas.
2010	Créditos insuficientes	Recargar créditos en la consola
2015	Versión obsoleta	Actualice a la última versión API
2018	Modelo demasiado complejo	Reducir la complejidad o el número de polígonos del modelo de entrada.

Ejemplos de manejo de errores

import time
import requests

def call_api_with_retry(url, headers, payload=None, max_retries=3):
    for attempt in range(max_retries):
        if payload:
            response = requests.post(url, headers=headers, json=payload)
        else:
            response = requests.get(url, headers=headers)

        if response.status_code == 200:
            return response.json()

        if response.status_code == 429:
            wait = 2 ** attempt
            print(f"Rate limit triggered. Retrying in {wait} seconds...")
            time.sleep(wait)
            continue

        error = response.json()
        raise Exception(
            f"API error [{error['code']}]: {error['message']} "
            f"(suggestion: {error.get('suggestion', 'none')})"
        )

    raise Exception("Maximum retry attempts exhausted")

async function callApiWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);

    if (response.ok) {
      return await response.json();
    }

    if (response.status === 429) {
      const wait = 2 ** attempt * 1000;
      console.log(`Rate limit triggered. Retrying in ${wait / 1000} seconds...`);
      await new Promise(resolve => setTimeout(resolve, wait));
      continue;
    }

    const error = await response.json();
    throw new Error(
      `API error [${error.code}]: ${error.message} (suggestion: ${error.suggestion || "none"})`
    );
  }

  throw new Error("Maximum retry attempts exhausted");
}

Recomendaciones de estrategia de reintento

Para errores reintentables, como límites de tasa 429 y errores de servicio 500, utilice una estrategia de retroceso exponencial:

Primer reintento: espera 1 segundo
Segundo reintento: espere 2 segundos
Tercer intento: espere 4 segundos
Mantenga el recuento máximo de reintentos en 5 o menos

Para errores que no se pueden reintentar, como 400, 401 y 403, genere una excepción directamente y solucione el problema subyacente.