Solução de problemas

O formato do erro corresponde ao protocolo que você chamou. /v1/chat/completions e /v1/responses retornam erros no formato OpenAI; /v1/messages retorna erros no formato Anthropic. Os códigos de status HTTP são idênticos nos três protocolos.

Formato da resposta de erro

Formato OpenAI (/v1/chat/completions, /v1/responses)

{
  "error": {
    "message": "Invalid API key",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}

Formato Anthropic (/v1/messages)

{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key"
  }
}

401 · Falha na autenticação authentication_error

{"error":{"message":"missing API key in Authorization header or X-API-Key","type":"authentication_error"}}

Causas

• Sem cabeçalho Authorization: Bearer (ou X-API-Key) — mensagem: missing API key in Authorization header or X-API-Key.
• A chave não corresponde a nenhuma chave ativa — mensagem: invalid API key.
• A chave expirou — mensagem: API key expired.

Correção

1. Envie Authorization: Bearer sk-syn-… (ou X-API-Key: sk-syn-…).
2. Confirme que a chave está ativa no console e que foi copiada por completo.

400 · Requisição inválida invalid_request

{"error":{"message":"model or models field is required","type":"invalid_request"}}

Causas

• O campo model está ausente, ou o corpo JSON está vazio ou malformado.

Correção

1. Inclua um model e um corpo JSON bem formado. Consulte a referência de Chat Completions.

403 · Cota esgotada quota_exhausted

{"error":{"message":"API key quota exhausted","type":"quota_exhausted"}}

Causas

• O saldo pré-pago da chave ou do espaço de trabalho acabou.

Correção

1. Recarregue o saldo do espaço de trabalho. Nota: a Synthorai retorna 403 quota_exhausted para saldo esgotado, não 429 — portanto o backoff exponencial não ajudará; apenas uma recarga resolve.

403 · Conformidade — sem compartilhamento de dados compliance_blocked / compliance_no_data_share

{"error":{"type":"compliance_blocked","code":"compliance_no_data_share","message":"model 'MODEL' is unavailable: your workspace compliance setting disallows providers that retain/train on data"}}

Causas

• Seu espaço de trabalho tem no_provider_data_share ativado, e o modelo solicitado só é oferecido por um provedor que exige retenção/compartilhamento de dados (por ex., um modelo do Bedrock ou Vertex apenas com compartilhamento de dados).

Correção

1. Encaminhe a requisição para um modelo sem retenção, ou desative o botão de conformidade do espaço de trabalho se o compartilhamento de dados for aceitável para essa carga. A classe de retenção é um critério de roteamento por modelo — veja a análise da retenção de 30 dias.

429 · Limite de taxa atingido rate_limit_exceeded

{"error":{"message":"rate limit exceeded: max 60 requests per minute","type":"rate_limit_exceeded"}}

Causas

• Você excedeu o teto de requisições por minuto (RPM). A mensagem indica o limite exato.

Correção

1. Aguarde e tente novamente com backoff exponencial + jitter (trecho abaixo). Solicite um limite maior se precisar de throughput sustentado.

502 · Nenhum canal para o modelo upstream_error

{"error":{"message":"no channels available for model \"MODEL\" in group \"default\"","type":"upstream_error"}}

Causas

• O id do modelo não corresponde a nenhum canal roteável para seu espaço de trabalho — um erro de digitação, um modelo removido ou um que seu plano não alcança.

Correção

1. Verifique o id exato na lista de modelos ao vivo. Se um modelo foi retirado recentemente, escolha um atual.

BYOK: erros do provedor upstream

Com bring-your-own-key, a requisição é executada na sua conta do provedor (AWS Bedrock, Google Vertex AI ou a API da Anthropic), então a Synthorai repassa o erro original do provedor sem alterações — as respostas trazem usage.is_byok: true. A correção fica no console ou na configuração desse provedor, não no gateway. Os mais comuns são as configurações de acesso a modelos e de compartilhamento de dados no nível da conta:

Erros do provedor upstream

Esses são repassados pelo provedor do modelo com o próprio status HTTP e type do provedor. Apenas 500 e 529 indicam o lado do provedor; trate-os (e 429) como transitórios e tente novamente, enquanto os 4xx refletem a requisição. Referência completa: a documentação de erros da Anthropic.

Limites de taxa

Os limites de taxa são aplicados por chave de API para garantir uso justo entre todos os usuários.

Limites padrão

Planejando o throughput de tokens com preços reais por token? Rode sua carga de trabalho na calculadora de custos de API LLM.

Tratamento de erros 429

import time
import openai

client = openai.OpenAI(base_url="https://synthorai.io/v1", api_key="YOUR_API_KEY")

for attempt in range(5):
    try:
        response = client.chat.completions.create(
            model="gpt-5.4-mini",
            messages=[{"role": "user", "content": "Hello"}]
        )
        break
    except openai.RateLimitError as e:
        wait = 2 ** attempt  # exponential backoff
        print(f"Rate limited. Retrying in {wait}s...")
        time.sleep(wait)

async function withRetry(fn, maxAttempts = 5) {
  for (let attempt = 0; attempt < maxAttempts; attempt++) {
    try {
      return await fn();
    } catch (err) {
      if (err.status === 429 && attempt < maxAttempts - 1) {
        const wait = Math.pow(2, attempt) * 1000;
        await new Promise(r => setTimeout(r, wait));
      } else throw err;
    }
  }
}

Recebendo um 502 ou sobrecarga em um modelo? Escolha uma alternativa na comparação de preços de modelos — cada modelo roteável e seu preço por token em uma única tabela.