Erros

Referência de códigos de erro HTTP da API Polar. Formato do corpo de erro, troubleshooting e soluções para cada tipo de erro.

Visão Geral

A API Polar utiliza códigos de status HTTP padrão para indicar o sucesso ou falha de uma requisição. Todas as respostas de erro seguem um formato consistente em JSON.

Formato do Corpo de Erro

Todas as respostas de erro incluem um corpo JSON com a seguinte estrutura:

{
  "error": {
    "message": "Descrição legível do erro",
    "type": "tipo_do_erro",
    "code": "codigo_especifico"
  }
}

Campo	Tipo	Descrição
`error.message`	string	Mensagem descritiva do erro
`error.type`	string	Categoria do erro
`error.code`	string	Código específico para tratamento programático

Códigos de Status HTTP

400 Bad Request

Requisição malformada ou parâmetros inválidos.

{
  "error": {
    "message": "O campo 'model' é obrigatório",
    "type": "invalid_request_error",
    "code": "missing_required_field"
  }
}

Causas comuns:

JSON malformado no corpo da requisição
Campo obrigatório ausente
Valor de parâmetro com tipo incorreto
Modelo não existente

Solução: Verifique o corpo da requisição e compare com a documentação do endpoint.

401 Unauthorized

Autenticação falhou.

{
  "error": {
    "message": "API key inválida ou ausente",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}

Causas comuns:

API key ausente no header Authorization
API key inválida ou revogada
Formato incorreto (deve ser Bearer pk-...)
JWT token expirado

Solução: Verifique sua API key e o formato do header Authorization: Bearer pk-sua-chave.

403 Forbidden

Permissão insuficiente para a operação.

{
  "error": {
    "message": "Escopo insuficiente para esta operação. Necessário: write",
    "type": "permission_error",
    "code": "insufficient_scope"
  }
}

Causas comuns:

API key sem o escopo necessário
IP não está no allowlist
Recurso pertence a outra conta

Solução: Use uma API key com os escopos corretos ou adicione o IP ao allowlist.

404 Not Found

Recurso não encontrado.

{
  "error": {
    "message": "Modelo 'urso-mega' não encontrado",
    "type": "not_found_error",
    "code": "model_not_found"
  }
}

Causas comuns:

URL do endpoint incorreta
ID de recurso inexistente
Modelo não disponível

Solução: Verifique a URL e os IDs utilizados. Consulte a lista de modelos disponíveis.

422 Unprocessable Entity

Requisição válida sintaticamente, mas semanticamente incorreta.

{
  "error": {
    "message": "O valor de 'temperature' deve estar entre 0.0 e 2.0",
    "type": "validation_error",
    "code": "invalid_parameter_value"
  }
}

Causas comuns:

Valores de parâmetros fora da faixa permitida
Combinação inválida de parâmetros
Conteúdo excede limite de tokens

Solução: Ajuste os valores dos parâmetros conforme a documentação.

429 Too Many Requests

Rate limit excedido.

{
  "error": {
    "message": "Rate limit excedido. Máximo de 200 requisições por minuto.",
    "type": "rate_limit_error",
    "code": "rate_limited"
  }
}

Causas comuns:

Muitas requisições em curto período
Limite de tokens por minuto atingido

Solução: Implemente retry com backoff exponencial. Consulte a página de Rate Limits.

500 Internal Server Error

Erro interno do servidor.

{
  "error": {
    "message": "Erro interno do servidor. Tente novamente.",
    "type": "server_error",
    "code": "internal_error"
  }
}

Causas comuns:

Erro temporário no servidor
Falha em serviço interno

Solução: Tente novamente após alguns segundos. Se persistir, contate o suporte.

503 Service Unavailable

Serviço temporariamente indisponível.

{
  "error": {
    "message": "Serviço temporariamente indisponível. Manutenção programada.",
    "type": "service_error",
    "code": "service_unavailable"
  }
}

Causas comuns:

Manutenção programada
Sobrecarga temporária
Modelo sendo atualizado

Solução: Aguarde e tente novamente. Verifique o status em status.polar-ai.com.

Tratamento de Erros

Python

import requests

response = requests.post(
    "https://api.polarai.com.br/v1/chat/completions",
    headers={"Authorization": "Bearer pk-sua-chave-aqui"},
    json={"model": "urso-mabe", "messages": [{"role": "user", "content": "Olá"}]}
)

if response.status_code != 200:
    error = response.json()["error"]
    print(f"Erro {response.status_code}: {error['message']}")
    print(f"Tipo: {error['type']}, Código: {error['code']}")
else:
    data = response.json()
    print(data["choices"][0]["message"]["content"])

TypeScript

try {
  const response = await fetch("https://api.polarai.com.br/v1/chat/completions", {
    method: "POST",
    headers: {
      "Authorization": "Bearer pk-sua-chave-aqui",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      model: "urso-mabe",
      messages: [{ role: "user", content: "Olá" }]
    })
  });

  if (!response.ok) {
    const { error } = await response.json();
    console.error(`Error ${response.status}: ${error.message}`);
    console.error(`Type: ${error.type}, Code: ${error.code}`);
    return;
  }

  const data = await response.json();
  console.log(data.choices[0].message.content);
} catch (e) {
  console.error("Network error:", e);
}

Tabela Resumo

Status	Tipo	Retentável	Ação
400	`invalid_request_error`	Não	Corrija a requisição
401	`authentication_error`	Não	Verifique a API key
403	`permission_error`	Não	Verifique escopos/IP
404	`not_found_error`	Não	Verifique URL/IDs
422	`validation_error`	Não	Ajuste parâmetros
429	`rate_limit_error`	Sim	Retry com backoff
500	`server_error`	Sim	Retry após espera
503	`service_error`	Sim	Retry após espera

On this page