Tratamento de erros

Formato unificado de resposta a erros

Todos os erros API retornam um 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	Descrição
code	inteiro	Código de erro
status	cadeia	Resultado da solicitação; `error` quando a solicitação falha
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 ou limite de simultaneidade excedido. Reduza a frequência de suas solicitações ou tente novamente mais tarde
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`
1007	Limite de taxa excedido	Reduza a frequência de solicitações e implemente novas tentativas com espera exponencial
2000	Limite de simultaneidade excedido	Aguarde a conclusão de uma tarefa da mesma categoria antes de criar outras ou espere o tempo indicado pelo cabeçalho de resposta `Retry-After`. Consulte Limites de taxa
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.