Erros

Toda resposta diferente de 2xx tem a mesma estrutura JSON — o padrão da OpenAI. Use error.code para o tratamento programático e status_code para a política de novas tentativas.

Dados do erro

{
  "error": {
    "message": "Model 'xyz-2025' is not available",
    "type": "model_not_found",
    "code": "model_not_found",
    "param": null
  }
}

Códigos de status HTTP

Códigos de erro comuns

authentication_error

• Esqueceu de definir o cabeçalho Authorization: Bearer ....
• A chave de API foi revogada em /app/keys.
• A chave ainda tem o prefixo incorreto (deve começar com sk-kn-).

insufficient_quota

• Saldo da carteira insuficiente para esta solicitação → error.code é insufficient_balance, e o erro informa quanto havia na carteira (balance_usd), quanto esta solicitação reserva (needed_usd), e dois links: topup_url abre a página de cobrança com uma recarga pré-selecionada, e auto_recharge_url abre as configurações de recarga automática. Nenhum dos links faz uma cobrança por si só.
• Limite mensal por chave atingido. A redefinição ocorre no início do mês civil (UTC). Aumente o limite em /app/keys.

{
  "error": {
    "message": "Wallet balance is too low for this request. Top up at https://kunavo.com/app/billing — or turn on auto-recharge there, and a saved card refills the wallet before requests are refused.",
    "type": "insufficient_quota",
    "code": "insufficient_balance",
    "param": null,
    "balance_usd": 0.0142,
    "needed_usd": 0.0381,
    "topup_url": "https://kunavo.com/app/billing?topup=20",
    "auto_recharge_url": "https://kunavo.com/app/billing?autorecharge=1&src=api_402"
  }
}

Pare de tentar novamente em insufficient_balance, a menos que a resposta tenha um cabeçalho Retry-After — ele significa que uma recarga automática já está cobrando seu cartão salvo, e a mesma solicitação deve funcionar alguns segundos depois.

permission_error

• A chave tem uma lista de permissões de IP, e sua chamada veio de um endereço fora dela. A mensagem informa o endereço detectado — adicione-o (ou seu bloco CIDR) em /app/keys ou remova totalmente a lista de permissões para permitir qualquer endereço.
• Mover um agente para um novo host, um novo gateway NAT ou um laptop em outra rede altera esse endereço. Uma chave sem lista de permissões nunca é recusada por esse motivo.

model_not_found

• Slug escrito incorretamente. Use /models para consultar a lista canônica.
• O modelo está desativado no momento (indisponibilidade upstream ou revisão de preços).

upstream_error

Indica que um provedor de modelos upstream retornou um erro que não conseguimos traduzir para um código mais específico. O corpo inclui a mensagem original. Causas comuns:

• Sobrecarga no provedor.
• Rejeição pela moderação de conteúdo (tente outro prompt).
• Restrição de região/disponibilidade.

Estratégia de novas tentativas

O padrão robusto mais simples: recuo exponencial com jitter somente para 429 / 5xx.

import time, random
from openai import OpenAI, RateLimitError, APIError

client = OpenAI(api_key=os.environ["KUNAVO_API_KEY"], base_url="https://api.kunavo.com/v1")

def call_with_retry(call, max_attempts=5):
    for attempt in range(max_attempts):
        try:
            return call()
        except RateLimitError:
            if attempt + 1 == max_attempts: raise
            # 429: exponential backoff with jitter
            time.sleep(min(2 ** attempt, 30) + random.random())
        except APIError as e:
            if e.status_code and 500 <= e.status_code < 600 and attempt + 1 < max_attempts:
                time.sleep(min(2 ** attempt, 30) + random.random())
            else:
                raise

result = call_with_retry(lambda: client.chat.completions.create(
    model="claude-haiku-4-5",
    messages=[{"role": "user", "content": "hi"}],
))

• Limite a espera a 30 segundos por tentativa e o total a 5 tentativas.
• Não tente novamente em erros 4xx (exceto 408 e 429). Isso só faz você perder tempo.
• A geração de imagens e vídeos não é idempotente: uma nova tentativa é uma nova geração e é cobrada se der certo. Uma chamada com falha nunca foi cobrada, então tentar de novo é seguro. Para vídeo, POST /v1/videos aceita um cabeçalho Idempotency-Key: um envio repetido com a mesma chave retorna a primeira tarefa.
• Para chats com efeitos colaterais no seu próprio código, elimine duplicatas usando uma chave de idempotência na camada da sua aplicação.

Depuração pelo painel

Todas as chamadas de API — bem-sucedidas ou com falha — estão visíveis em /app/usage. Clique em qualquer linha para abrir a página com os detalhes completos da solicitação/resposta:

• Código de status HTTP retornado ao cliente.
• Código de erro upstream (quando aplicável).
• Latência, IP da solicitação e user-agent.
• Filtrar por status ajuda a identificar padrões (por exemplo, todos os erros 422 em um modelo específico).

Como relatar um incidente

Se houver erros 5xx persistentes em um modelo que deveria funcionar, envie um e-mail para support@kunavo.com com:

• O slug do modelo e um exemplo de corpo da solicitação (remova os segredos).
• O período em que ocorreram as falhas.
• O erro code + message da resposta.
• Se possível, um link para o registro de uso em /app/usage/[id].

Prazo de resposta de um dia útil; mais rápido para problemas urgentes que afetem a receita.

Próximos passos

• Como a cobrança afeta os erros 402/limite de cota
• Gerenciamento de chaves de API