> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Códigos de erro da API

> Referência de todos os códigos de erro da API do Toqan Router, com status HTTP, causa e solução, abrangendo erros de autenticação, validação, limite de taxa e provedor.

Toda resposta de erro da API do **Toqan Router** inclui um objeto `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:**

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "error": {
    "code": "invalid_api_key",
    "message": "The provided API key is invalid.",
    "doc_url": "/errors/invalid_api_key"
  }
}
```

## Referência rápida

| Código | HTTP | Categoria |
| - | - | - |
| [authentication\_required](#authentication_required) | 401 | Autenticação |
| [invalid\_api\_key](#invalid_api_key) | 401 | Autenticação |
| [expired\_api\_key](#expired_api_key) | 401 | Autenticação |
| [insufficient\_scope](#insufficient_scope) | 403 | Autenticação |
| [wrong\_project](#wrong_project) | 403 | Autenticação |
| [workspace\_disabled](#workspace_disabled) | 403 | Autenticação |
| [workspace\_archived](#workspace_archived) | 403 | Autenticação |
| [quota\_exceeded](#quota_exceeded) | 402 | Cota |
| [invalid\_request\_body](#invalid_request_body) | 400 | Validação |
| [unsupported\_engine](#unsupported_engine) | 400 | Validação |
| [variant\_not\_resolved](#variant_not_resolved) | 422 | Validação |
| [model\_configuration\_missing](#model_configuration_missing) | 422 | Validação |
| [provider\_credential\_invalid](#provider_credential_invalid) | 422 | Validação |
| [guardrail\_not\_found](#guardrail_not_found) | 422 | Validação |
| [guardrail\_execution\_failed](#guardrail_execution_failed) | 502 | Servidor |
| [deployment\_not\_found](#deployment_not_found) | 404 | Não encontrado |
| [integration\_not\_found](#integration_not_found) | 404 | Não encontrado |
| [prompt\_snippet\_not\_found](#prompt_snippet_not_found) | 404 | Não encontrado |
| [rate\_limit\_exceeded](#rate_limit_exceeded) | 429 | Limite de taxa |
| [provider\_error](#provider_error) | 502 | Provedor |
| [provider\_timeout](#provider_timeout) | 504 | Provedor |
| [provider\_overloaded](#provider_overloaded) | 503 | Provedor |
| [internal\_error](#internal_error) | 500 | Servidor |
| [not\_implemented](#not_implemented) | 501 | Servidor |
| [service\_unavailable](#service_unavailable) | 503 | Servidor |
| [request\_timeout](#request_timeout) | 408 | Servidor |

***

## 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 header `Authorization`:

```
Authorization: Bearer sk-orq-...
```

***

### invalid\_api\_key

**Status HTTP:** 401

**Quando ocorre:** a chave de API informada no header `Authorization` é 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. Os `details` 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. Os `details` 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. Os `details` 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. Os `details` 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 uma `message` 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:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "message": "This workspace is blocked and cannot process requests."
}
```

Um bloqueio decorre de um problema de cobrança, como uma fatura não paga ou um pagamento que falhou. Ele também pode revogar as chaves de API do workspace, e uma chave revogada responde com esta mensagem.

**Como corrigir:** quite o saldo pendente ou atualize a forma de pagamento em Cobrança. Uma chave revogada continua revogada; portanto, crie uma nova chave de API depois que o bloqueio for removido.

***

### workspace\_archived

**Status HTTP:** 403

**Quando ocorre:** o workspace está arquivado. O gateway responde com:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "code": "workspace_archived",
  "message": "This workspace has been archived and cannot process requests. Restore the workspace to resume access."
}
```

**Como corrigir:** restaure o workspace em **Settings** → **Organization** → **General**, conforme descrito em Configurações do workspace, e tente a requisição novamente.

Ambos diferem de [workspace\_disabled](#workspace_disabled), que é um 403 na chave de API da plataforma, e não na assinatura do workspace.

***

## Cota

### quota\_exceeded

**Status HTTP:** 402

**Quando ocorre:** o workspace atingiu o limite de um recurso no plano atual. Os `details` 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:**

| Entidade | Developer | Growth | Enterprise |
| - | - | - | - |
| Deployments | 3 | Ilimitado | Ilimitado |
| Agents | 3 | Ilimitado | Ilimitado |
| Knowledge Bases + Memory Stores | 2 | Ilimitado | Ilimitado |
| Webhooks | 1 | 5 | Ilimitado |

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. Os `details` 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 de `model` 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](/docs/pt-BR/ai-gateway/using-the-router.md) 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 ao `context` 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. Os `details` 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. Os `details` 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. Os `details` 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. Os `details` 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 a `key` 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. Os `details` 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 uma `key` 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. Os `details` 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. Os `details` 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. Os `details` 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. Os `details` 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. Os `details` 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. Os `details` 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. Os `details` 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`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.