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

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

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:

Primeira tentativa: espere 1 segundo
Segunda tentativa: aguarde 2 segundos
Terceira tentativa: aguarde 4 segundos
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.