Erros e limites

O erro chega no formato da API que chamou: objeto error para OpenAI, {"type": "error", "error": {...}} para Anthropic e error com os campos status e details para Gemini. Por isso, os SDK reconhecem-nos como erros normais da API.

• error.code e error.reason — classe do erro da tabela abaixo; os dois coincidem. error.type — valor padrão do formato (por exemplo, invalid_request_error ou server_error).
• error.request_id (em Anthropic — request_id no nível superior), o cabeçalho X-Request-ID e o fim do texto da mensagem — identificador do pedido.
• Em Gemini, a classe está em error.details: ErrorInfo.reason — o mesmo código em maiúsculas (por exemplo, MODEL_OVERLOADED), domain — ailoot.ai; o identificador do pedido está em RequestInfo.requestId.
• No formato Gemini, um erro 5xx que não deve ser repetido automaticamente e result_pending_check chegam com o estado 409 e status ABORTED: assim, o Gemini SDK e o CLI não os repetem automaticamente. A classe do erro está em ErrorInfo.reason (por exemplo, MODEL_TIMEOUT ou RESULT_PENDING_CHECK).
• A resposta no formato OpenAI também inclui campos de nível superior code e message — para clientes antigos.

{
  "code": "API_KEY_REQUIRED",
  "error": {
    "code": "invalid_api_key",
    "message": "No API key was sent with the request. Nothing was charged. Please check that the full key is sent in the Authorization header as \"Bearer <key>\". Request ID: 3b28d3de-5b02-4d07-9f3c-4b9a7d0e68d6.",
    "param": null,
    "reason": "invalid_api_key",
    "request_id": "3b28d3de-5b02-4d07-9f3c-4b9a7d0e68d6",
    "type": "invalid_request_error"
  },
  "message": "No API key was sent with the request. Nothing was charged. …"
}

{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "reason": "invalid_api_key",
    "message": "… Nothing was charged. … Request ID: 94ed3e31-4373-41ce-bf8a-0d1ed3f7235e."
  },
  "request_id": "94ed3e31-4373-41ce-bf8a-0d1ed3f7235e"
}

{
  "error": {
    "code": 401,
    "status": "UNAUTHENTICATED",
    "message": "The API key is not valid. Nothing was charged. … Request ID: e7aa743b-9d0d-4064-b206-2562609f545b.",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "INVALID_API_KEY",
        "domain": "ailoot.ai",
        "metadata": {
          "code": "invalid_api_key",
          "reason": "invalid_api_key",
          "request_id": "e7aa743b-9d0d-4064-b206-2562609f545b"
        }
      },
      {
        "@type": "type.googleapis.com/google.rpc.RequestInfo",
        "requestId": "e7aa743b-9d0d-4064-b206-2562609f545b"
      }
    ]
  }
}

Os códigos de resposta do modelo e de verificação do resultado (502, 503 e 504) referem agora o modelo ou o pedido: model_unavailable, model_timeout, invalid_model_response, incomplete_response, charge_not_confirmed e result_pending_check. Se o seu código comparar error.code com valores anteriores, substitua-os pelos códigos da tabela; para saber a correspondência entre códigos antigos e novos, contacte o suporte.

• Consulte primeiro X-Should-Retry: se for false, result_pending_check ou model_timeout não repita automaticamente. Procure o Request ID no histórico da área pessoal: aí poderá ver o resultado e o débito.
• É seguro repetir quando receber X-Should-Retry: true: aguarde Retry-After segundos. Para 5xx, o código por si só não basta: o resultado pode já ter aparecido. Consulte primeiro o histórico da área pessoal ou contacte o suporte com o Request ID. Isto é especialmente importante para imagens, vídeo, música e passos longos de agentes.
• Repetir não ajuda: 400, 401, 402, 403, 404 — corrija primeiro o pedido, a chave ou o saldo.

A frequência e o número de pedidos simultâneos são limitados para a conta no seu conjunto, e não por chave. Se exceder o limite, receberá 429 rate_limit_exceeded com o cabeçalho Retry-After: 10. Se for o próprio modelo a estar sobrecarregado — 503 model_overloaded com Retry-After: 30. Se precisar de uma carga maior, contacte o suporte.

Os limites de despesas são definidos na chave: limite total — 402 api_key_quota_exhausted, janelas de 5 horas, 1 dia e 7 dias — 429 usage_limit_reached. Saiba mais — Chaves e endereço da API.

Pode consultar a lista de modelos mesmo com saldo zero; a geração exige saldo para a reserva. Os modelos NVIDIA (Nemotron e outros) funcionam através de uma fila partilhada: com carga elevada, a resposta pode demorar mais ou receberá um erro «modelo temporariamente sobrecarregado» com o cabeçalho Retry-After — repita após o tempo indicado. Os preços estão no catálogo e o débito funciona como nos restantes modelos.

Os limites de tamanho são definidos pelo modelo: contexto (quantos tokens pode enviar) e comprimento máximo da resposta. Estão indicados no catálogo.