Developer guide
Códigos de erro
Ações e regras de nova tentativa por código de status
Esta página organiza os códigos de status retornados pelo gateway, seus significados e as ações correspondentes a cada código.
Quando o upstream retorna 4xx·5xx, o código é encaminhado sem alterações; nos demais casos, aplica-se a tabela abaixo.
Também descrevemos o formato do corpo de erro dos dois padrões compatíveis, as regras de error.type compatível com Anthropic e a tela do console para verificar limites e uso.
Código de status
| Código | Significado | Ação |
|---|---|---|
| 400 | Erro nos valores da solicitação. O limite da lista de modelos compatíveis com Anthropic está fora de 1~1000 ou houve uma tentativa de retomar uma resposta armazenada usando GET /responses/{responseId}?stream=true | Ajuste o valor para que fique dentro do intervalo. Consulte as respostas armazenadas sem stream. |
| 401 | Chave ausente ou chave expirada·revogada | Verifique o status da chave na tela de chaves da API e confira o nome do cabeçalho e o prefixo Bearer. |
| 403 | Sem permissão para acessar o modelo, limite de uso excedido, créditos insuficientes ou não é o proprietário da voz | error.message distingue o motivo. Consulte os valores na tela da seção abaixo sobre verificação de limites e uso. |
| 404 | Modelo inexistente ou inacessível com esta chave (incluindo modelos cujo suporte foi encerrado), caminho inexistente ou artefato do CleviDrive cujo período de retenção de 3 dias expirou | Primeiro, verifique a lista de modelos que podem ser chamados com GET /models. Compare o caminho com a tabela da página Fazer chamadas à API. |
| 408 · 409 · 413 | Tempo limite excedido no upstream, congestionamento ou tamanho da solicitação excedido. Para rotas de áudio·voz, o tempo limite é de 5 minutos e o limite da solicitação é de 28 MiB | Se 409 incluir Retry-After, aguarde esse período. Para 413, divida a solicitação antes de enviá-la. |
| 429 | O provedor upstream aplicou uma limitação de velocidade | Se Retry-After for retornado, siga-o exatamente; caso contrário, faça novas tentativas com backoff exponencial. |
| 5xx | Erro temporário do gateway ou do upstream (incluindo 503) | Faça novas tentativas com backoff exponencial. Se o problema persistir, informe-o na Central de ajuda e no contato, incluindo X-Request-Id. |
Nova tentativa
O gateway não gera seu próprio 429, nem tenta novamente ou coloca em fila silenciosamente as respostas do upstream.
O cliente é responsável por aguardar e fazer novas tentativas.
| Código | Tempo de espera | Em seguida |
|---|---|---|
| 409 | Se houver Retry-After, aguarde esse tempo | Envie a mesma solicitação novamente. |
| 429 | Se houver Retry-After, aguarde esse tempo; caso contrário, use recuo exponencial | Envie a mesma solicitação novamente. |
| 5xx | Recuo exponencial | Se persistir, entre em contato. |
| 413 | Sem espera | Divida a solicitação. |
Corpo do erro
O formato do corpo do erro varia conforme a especificação. Os erros upstream são organizados, mantendo apenas a mensagem, e encaminhados sem a pilha nem os campos internos.
Este é o corpo do caminho compatível com OpenAI.
{
"error": {
"message": "API key is required.",
"type": "invalid_request_error"
}
}Este é o corpo do caminho compatível com Anthropic. error.type é definido pelo código de status.
{
"type": "error",
"error": {
"type": "authentication_error",
"message": "..."
},
"request_id": "rqid..."
}| Código de status | error.type |
|---|---|
| 400 | invalid_request_error |
| 401 | authentication_error |
| 403 | permission_error |
| 404 | not_found_error |
| 413 | request_too_large |
| 429 | rate_limit_error |
| 529 | overloaded_error |
| Outros códigos | api_error |
Verificar limites e uso
Os valores dos limites variam de acordo com o workspace. Verifique o motivo do 403 em error.message e consulte os valores nas telas abaixo.
| O que verificar | Tela do console |
|---|---|
| Limite aplicado ao meu workspace | Limite de uso alocado na visão geral |
| Faixa permitida pelo plano e saldo | Plano e créditos |
| Uso real (chamadas por modelo e por chave, créditos estimados a serem descontados) | Uso |
| Status da chave (se está expirada ou revogada) | Chaves de API |