# Manejo de errores

## Formato de respuesta de error unificado

Todos los errores API devuelven un formato JSON unificado:

```json
{
  "code": 2010,
  "message": "Insufficient credits",
  "suggestion": "Please top up your account at https://platform.tripo3d.ai",
  "request_id": "req_abc123"
}
```

| campo | Tipo | Descripción |
| :-: | :-: | :-: |
| code | entero | código de error |
| 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 tarifa. Reduzca la frecuencia de sus solicitudes |
| 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` |
| 2000 | Límite de tarifa excedido | Reduzca la frecuencia de solicitudes e implemente reintentos con retroceso exponencial |
| 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

### Python

```python
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")
```

### JavaScript

```javascript
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:

1. Primer reintento: espera 1 segundo
2. Segundo reintento: espere 2 segundos
3. Tercer intento: espere 4 segundos
4. 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.