error com os campos code, message e doc_url. Use o code para identificar a falha exata e siga as etapas de resolução abaixo.
Formato da resposta de erro:
Referência rápida
Erros de autenticação
authentication_required
Status HTTP: 401 Quando ocorre: a requisição não incluiu um header de autenticação válido. Como corrigir: inclua uma chave de API válida do Toqan Router em todas as requisições usando o headerAuthorization:
invalid_api_key
Status HTTP: 401 Quando ocorre: a chave de API informada no headerAuthorization é inválida.
Como corrigir: verifique se a chave foi copiada corretamente, sem espaços em branco no início ou no fim.
expired_api_key
Status HTTP: 401 Quando ocorre: a chave de API passou da data de expiração. Osdetails do erro incluem expired_at (timestamp ISO).
Como corrigir: crie uma nova chave de API e atualize-a em todos os lugares onde ela é usada.
insufficient_scope
Status HTTP: 403 Quando ocorre: a chave de API não tem a permissão necessária para a operação solicitada. Osdetails do erro incluem a permissão required e o scope da chave (PUBLIC, WORKSPACE ou PROJECT).
Como corrigir: use uma chave com permissões mais amplas ou crie uma nova chave com o nível de permissão necessário.
wrong_project
Status HTTP: 403 Quando ocorre: a chave de API está restrita a um projeto específico, mas o recurso acessado pertence a outro projeto. Osdetails do erro incluem key_project_id e resource_project_id.
Como corrigir: use uma chave de API restrita ao projeto correto.
workspace_disabled
Status HTTP: 403 Quando ocorre: o workspace associado à chave de API foi desativado. Osdetails do erro podem incluir um reason.
Como corrigir: entre em contato com o administrador do workspace para investigar o status do workspace.
Erros de conta e workspace
Essas respostas vêm do gateway antes que a requisição chegue a um modelo. O caso de bloqueio responde com umamessage simples e sem code; o caso de arquivamento adiciona um code.
workspace_blocked
Status HTTP: 401 Quando ocorre: o workspace está bloqueado. O gateway responde antes de ler o corpo da requisição:workspace_archived
Status HTTP: 403 Quando ocorre: o workspace está arquivado. O gateway responde com:Cota
quota_exceeded
Status HTTP: 402 Quando ocorre: o workspace atingiu o limite de um recurso no plano atual. Osdetails do erro incluem usage (contagem atual) e limit (máximo do plano).
Como corrigir: exclua recursos não utilizados para liberar cota ou faça upgrade do plano.
Limites dos planos:
Knowledge Bases e Memory Stores compartilham um único limite combinado.
Para aumentar os limites, entre em contato com o administrador do workspace.
Erros de validação
invalid_request_body
Status HTTP: 400 Quando ocorre: o corpo da requisição falhou na validação do schema. Osdetails do erro incluem um array issues que descreve cada falha de validação.
Como corrigir: inspecione o array issues na resposta de erro para identificar os campos que falharam na validação. Corrija o corpo da requisição para que corresponda ao schema esperado.
unsupported_engine
Status HTTP: 400 Quando ocorre: o valor demodel na requisição faz referência a um engine que não é suportado. Os details do erro incluem o engine solicitado e um array supported com os engines válidos.
Como corrigir: use um dos identificadores de modelo da lista supported ou consulte a página Modelos para ver as opções disponíveis.
variant_not_resolved
Status HTTP: 422 Quando ocorre: o deployment tem várias variantes configuradas, mas nenhuma delas correspondeu aocontext informado na requisição. Os details do erro incluem as context_keys que foram avaliadas.
Como corrigir: garanta que o objeto context na requisição contenha as chaves esperadas pelas regras de variante do deployment.
model_configuration_missing
Status HTTP: 422 Quando ocorre: não foi possível carregar o modelo atribuído ao deployment. Osdetails do erro incluem model_db_id.
Como corrigir: verifique se o modelo atribuído ao deployment ainda está disponível. Se o problema persistir, entre em contato com o administrador do workspace.
provider_credential_invalid
Status HTTP: 422 Quando ocorre: a credencial do provedor armazenada para a integração não pôde ser descriptografada ou está malformada. Osdetails do erro incluem o nome do provider e o field que falhou.
Como corrigir: insira novamente a credencial do provedor afetado em Integrations.
guardrail_not_found
Status HTTP: 422 Quando ocorre: o Deployment ou o Agent ainda faz referência a um Evaluator de guardrail que já foi excluído, então o guardrail não pode ser executado. Osdetails do erro incluem o evaluator_id que não pôde ser resolvido. As requisições falham de forma fechada (fail closed): nenhuma resposta é retornada enquanto houver um guardrail não resolvível configurado.
Como corrigir: abra as configurações do Deployment ou do Agent afetado. O guardrail excluído aparece como uma entrada ausente na seção Guardrails. Remova-o ou aponte a configuração para um Evaluator existente e salve.
guardrail_execution_failed
Status HTTP: 502 Quando ocorre: um guardrail configurado não pôde ser avaliado, por exemplo porque o runtime do evaluator retornou um erro. Os guardrails falham de forma fechada (fail closed), então a requisição é rejeitada em vez de passar sem verificação. Osdetails do erro incluem o evaluator_id e, quando disponível, o reason informado pelo runtime do evaluator.
Como corrigir: inspecione o span do evaluator em Traces para ver a falha subjacente. Corrija a definição do evaluator se o reason apontar para a configuração ou o código dele. Tente a requisição novamente se a falha for transitória e entre em contato com o administrador do workspace se ela persistir.
Não encontrado
deployment_not_found
Status HTTP: 404 Quando ocorre: não existe nenhum deployment com akey informada na requisição. Os details do erro incluem a key que foi buscada.
Como corrigir: confira a chave do deployment na lista em AI Studio > Deployments. As chaves diferenciam maiúsculas de minúsculas.
integration_not_found
Status HTTP: 404 Quando ocorre: o identificador de integração referenciado na requisição não existe no workspace. Osdetails do erro incluem o identifier.
Como corrigir: verifique em Integrations se a integração existe. Garanta que o identificador esteja escrito corretamente.
prompt_snippet_not_found
Status HTTP: 404 Quando ocorre: um template de prompt faz referência a um snippet com umakey que não existe. Os details do erro incluem a key que foi buscada.
Como corrigir: crie o snippet ausente ou atualize o template de prompt para fazer referência a uma chave de snippet existente.
Limite de taxa
rate_limit_exceeded
Status HTTP: 429 Quando ocorre: as requisições estão sendo enviadas mais rápido do que a taxa permitida para o workspace. Osdetails do erro incluem retry_after_seconds (quanto tempo esperar antes de tentar novamente) e, opcionalmente, limit (o limite de taxa).
Como corrigir: aguarde pelo menos retry_after_seconds antes de tentar novamente. Implemente backoff exponencial na aplicação. Para solicitar um aumento de limite, entre em contato com o administrador do workspace.
Erros de provedor
provider_error
Status HTTP: 502 Quando ocorre: o provedor de IA upstream retornou uma resposta de erro. Osdetails do erro incluem o nome do provider, o código HTTP provider_status quando disponível e uma string de erro raw quando disponível.
Como corrigir: verifique a página de status do provedor para ver se há incidentes ativos. Tente a requisição novamente após um breve intervalo.
provider_timeout
Status HTTP: 504 Quando ocorre: o provedor upstream não respondeu dentro da janela de tempo permitida. Osdetails do erro incluem o nome do provider e timeout_ms (o timeout que foi excedido).
Como corrigir: tente a requisição novamente. Para respostas consistentemente lentas, considere reduzir o tamanho do prompt ou do contexto, ou mudar para um modelo mais rápido.
provider_overloaded
Status HTTP: 503 Quando ocorre: o provedor upstream está temporariamente sobrecarregado e rejeitou a requisição. Osdetails do erro incluem o nome do provider.
Como corrigir: tente novamente com backoff exponencial.
Erros de servidor
internal_error
Status HTTP: 500 Quando ocorre: ocorreu um erro inesperado dentro do Toqan Router. Ele não é causado pela própria requisição. Como corrigir: tente a requisição novamente. Se o erro persistir, entre em contato com o administrador do workspace.not_implemented
Status HTTP: 501 Quando ocorre: o recurso solicitado ainda não foi implementado. Osdetails do erro incluem o nome do feature.
Como corrigir: entre em contato com o administrador do workspace para mais informações.
service_unavailable
Status HTTP: 503 Quando ocorre: uma dependência interna necessária (banco de dados, cache etc.) está temporariamente indisponível. Osdetails do erro podem incluir o nome da dependency.
Como corrigir: tente a requisição novamente após um breve intervalo.
request_timeout
Status HTTP: 408 Quando ocorre: a requisição levou mais tempo do que o tempo máximo de processamento permitido pelo servidor. Osdetails do erro incluem timeout_ms.
Como corrigir: reduza a complexidade da requisição: prompts mais curtos, menos tokens de contexto ou um valor menor de max_tokens.