# Tratamento de erros

## Formato unificado de resposta a erros

Todos os erros API retornam um 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 | Descrição |
| :-: | :-: | :-: |
| code | inteiro | Código de erro |
| message | cadeia | Descrição do erro |
| suggestion | cadeia | Correção sugerida |
| request_id | cadeia | Identificador de solicitação exclusivo para solução de problemas |

## Códigos de status HTTP

| Código de status | Significado | Descrição |
| :-: | :-: | :-: |
| 200 | Sucesso | A solicitação foi processada com sucesso |
| 400 | Parâmetros inválidos | Os parâmetros obrigatórios estão ausentes ou mal formados |
| 401 | Não autenticado | O API Key está ausente ou é inválido |
| 403 | Permissões insuficientes | Você não tem permissão para acessar o recurso ou seus créditos são insuficientes |
| 404 | Recurso não encontrado | A tarefa ou recurso solicitado não existe |
| 429 | Muitos pedidos | Limite de taxa excedido. Reduza a frequência de suas solicitações |
| 500 | Erro de serviço | Erro interno do servidor. Tente novamente mais tarde |

## Referência de código de erro

| Código de erro | Significado | Manuseio recomendado |
| :-: | :-: | :-: |
| 1000 | API Key inválido | Verifique se o API Key está correto ou foi excluído |
| 1001 | Não autorizado | Verifique se o cabeçalho da solicitação inclui `Authorization` |
| 2000 | Limite de taxa excedido | Reduza a frequência de solicitações e implemente novas tentativas com espera exponencial |
| 2002 | Parâmetro de solicitação não compatível | Verifique se os nomes e valores dos campos do corpo da solicitação correspondem à documentação |
| 2003 | Arquivo de entrada vazio | Confirme se o arquivo enviado não está vazio e usa um formato válido |
| 2004 | Tipo de arquivo não suportado | Verifique se o formato do arquivo está na lista suportada |
| 2008 | Violação da política de conteúdo | Modifique o conteúdo de entrada para evitar palavras ou imagens proibidas |
| 2010 | Créditos insuficientes | Recarregue créditos no console |
| 2015 | Versão obsoleta | Atualize para a versão mais recente do API |
| 2018 | Modelo muito complexo | Reduza a complexidade ou a contagem múltipla do modelo de entrada |

## Exemplos de tratamento de erros

### 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");
}
```

## Recomendações de estratégia para tentar novamente

Para erros repetíveis, como limites de taxa 429 e 500 erros de serviço, use uma estratégia de espera exponencial:

1. Primeira tentativa: espere 1 segundo
2. Segunda tentativa: aguarde 2 segundos
3. Terceira tentativa: aguarde 4 segundos
4. Mantenha a contagem máxima de novas tentativas em 5 ou menos

Para erros que não podem ser repetidos, como 400, 401 e 403, lance uma exceção diretamente e corrija o problema subjacente.