Source: https://ailoot.ai/docs/pt-pt/errors/ Canonical: https://ailoot.ai/docs/pt-pt/errors/ Language: pt-pt [Ajuda](https://ailoot.ai/docs/pt-pt/) # Erros e limites [Markdown](https://ailoot.ai/docs/pt-pt/errors/index.md) Códigos de resposta, o seu significado e o que fazer. Todos os erros são apresentados em JSON e incluem o Request ID. ## [](https://ailoot.ai/docs/pt-pt/errors/#format)Formato do erro 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. ```json { "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 \". 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. …" } ``` ```json { "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" } ``` ```json { "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" } ] } } ``` “Nothing was charged” significa que não foi debitado dinheiro. Se receber X-Should-Retry: false, não repita automaticamente; consulte primeiro o Request ID no histórico. ## [](https://ailoot.ai/docs/pt-pt/errors/#codes)Códigos de erro | HTTP | Classe (reason) | O que aconteceu | O que fazer | | --- | --- | --- | --- | | 400 | `invalid_request` | Pedido inválido: corpo ou parâmetro incorreto; o modelo não suporta um campo, anexo ou ferramenta do pedido; a chave foi transmitida no endereço | Corrija o pedido de acordo com o texto do erro: remova o campo, anexo ou ferramenta não suportado; envie a chave num cabeçalho. A rejeição por um campo, anexo ou ferramenta não suportado ocorre antes da reserva — não há qualquer débito | | 400 | `context_length_exceeded` | O pedido excede o contexto do modelo | Reduza o histórico ou escolha um modelo com contexto maior | | 400 | `content_policy_violation` | O pedido foi rejeitado pelas regras do modelo | Reformule o pedido | | 401 | `invalid_api_key` | A chave está em falta ou é inválida | Verifique se a chave foi transmitida na íntegra | | 401 | `api_key_disabled` | A chave está desativada | Ative a chave ou crie uma nova | | 402 | `insufficient_balance`, `insufficient_quota` | O saldo disponível não chega sequer para a reserva mínima (`insufficient_quota` — o mesmo caso apresentado na forma habitual do OpenAI SDK) | Carregue o saldo ou reduza max\_tokens | | 402 | `api_key_quota_exhausted` | O limite total de despesas da chave está esgotado | Aumente o limite da chave na área pessoal | | 402 | `payment_disputed` | A conta tem uma dívida por um pagamento contestado | Os novos pedidos estão suspensos até à liquidação da dívida — contacte o suporte | | 403 | `api_key_expired` | A chave expirou | Crie uma nova chave | | 403 | `account_inactive` | A sua conta está desativada | Contacte o suporte | | 403 | `permission_denied` | A chave não tem permissão para este pedido (por exemplo, devido ao IP) | Verifique as restrições da chave | | 404 | `model_not_found` | O modelo não existe | Compare o ID com /v1/models | | 404 | `unsupported_endpoint` | O modelo não funciona neste formato | Escolha outro formato ou modelo | | 404 | `not_found` | O caminho ou objeto não existe (por exemplo, uma tarefa) | Verifique o endereço e o identificador | | 409 | `duplicate_request` | Uma operação com a mesma chave de idempotência já foi aceite e pode estar concluída | Verifique o resultado da primeira operação; não envie uma nova | | 409 | `not_ready`, `video_not_ready` | O vídeo ou outra tarefa ainda não está concluído | Consulte o estado mais tarde | | 409, 503 | `result_pending_check` | Estamos a verificar o resultado do pedido. Numa tarefa de vídeo, é a indicação `result_pending_check: true` na resposta de estado; a tarefa permanece em `in_progress` | Não repita o pedido — o estado aparecerá no histórico (GET https://ailoot.ai/api/v1/usage). Não volte a criar a tarefa de vídeo: consulte-a mais tarde através de GET /v1/videos/{id} | | 410 | `model_retired` | O modelo foi retirado de serviço | Escolha uma nova versão em GET /v1/models | | 413 | `request_too_large` | O corpo do pedido é demasiado grande | Reduza os ficheiros ou o histórico | | 429 | `rate_limit_exceeded`, `gateway_concurrency_limit`, `gateway_queue_full` | Demasiados pedidos ou pedidos simultâneos da sua conta | Aguarde (cabeçalho `Retry-After`, normalmente 10 s) e tente novamente | | 429 | `usage_limit_reached` | A janela de despesas da chave está esgotada (5 horas, 1 dia ou 7 dias) | Aguarde a renovação da janela ou aumente o limite da chave | | 500 | `internal_error` | Erro do Ailoot | Contacte o suporte com o Request ID | | 502 | `invalid_model_response`, `empty_response`, `incomplete_response` | O modelo devolveu uma resposta inválida, vazia ou incompleta | Procure o Request ID no histórico da área pessoal. Se existir um resultado ou débito, a repetição criará um segundo pedido pago. A ausência de um registo não confirma que o pedido não tenha sido enviado ou executado: não repita um envio não confirmado; contacte o suporte com o Request ID. | | 502 | `result_not_delivered` | O resultado não foi entregue por responsabilidade do Ailoot; a reserva ou o débito foi devolvido | Pode voltar a enviar o pedido | | 503 | `model_overloaded` | O modelo está temporariamente sobrecarregado | Se X-Should-Retry: true — tente novamente após o número de segundos de Retry-After; se false — consulte primeiro o Request ID no histórico | | 503 | `model_unavailable` | O modelo está temporariamente indisponível | Escolha outro modelo. Se X-Should-Retry: true — tente novamente após o número de segundos de Retry-After; se false — consulte primeiro o Request ID no histórico | | 503 | `service_unavailable` | Falha temporária do Ailoot | Se X-Should-Retry: true — tente novamente após o número de segundos de Retry-After; se false — consulte primeiro o Request ID no histórico | | 503 | `charge_not_confirmed` | A resposta não foi entregue: não foi possível confirmar o débito; a reserva foi devolvida e não foi debitado dinheiro | Se X-Should-Retry: true — tente novamente após o número de segundos de Retry-After; se false — consulte primeiro o Request ID no histórico | | 504 | `model_timeout` | O modelo não respondeu a tempo; o resultado ainda pode aparecer | Não volte a enviar o pedido antes de consultar o Request ID no histórico | 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](https://ailoot.ai/docs/pt-pt/support/). ## [](https://ailoot.ai/docs/pt-pt/errors/#retry)Quando repetir um pedido - **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. Os SDK OpenAI e Anthropic costumam repetir automaticamente erros de rede e 5xx. Para gerações, desative esse comportamento (`max_retries=0`) e consulte `X-Should-Retry` antes de uma nova tentativa. Perder a resposta não significa que o pedido não foi executado. ## [](https://ailoot.ai/docs/pt-pt/errors/#limits)Limites 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](https://ailoot.ai/docs/pt-pt/support/). 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](https://ailoot.ai/docs/pt-pt/keys/#key). ## [](https://ailoot.ai/docs/pt-pt/errors/#nvidia)Modelos NVIDIA: fila 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](https://ailoot.ai/models/pt-pt/). ## Histórico e despesas [Histórico e despesas](https://ailoot.ai/usage) · [GET https://ailoot.ai/api/v1/usage](https://ailoot.ai/docs/pt-pt/cabinet/usage/) · JWT · `Authorization: Bearer $TOKEN` `JWT ≠ sk-…` · [Início de sessão e sessões](https://ailoot.ai/docs/pt-pt/cabinet/auth/) Ainda tem dúvidas? Envie o Request ID e uma descrição — ajudamos a esclarecer.[Contactar o suporte](mailto:support@ailoot.ai) ## Ailoot · A empresa e a sua carteira de projetos A Ailoot assenta numa experiência operacional consolidada, numa ampla base de clientes, num serviço estável e no acompanhamento contínuo dos KPI. A empresa e a sua carteira de projetos: milhões de clientes; vendas mensais na ordem dos milhares de milhões. A Ailoot aplica essa experiência operacional ao acesso por API a funcionalidades de IA nos produtos dos clientes, agentes, aplicações e automatizações.