Developer guide
Código de erro
Procedimentos e regras de nova tentativa por código de status
Quando o upstream retorna 4xx ou 5xx, o gateway encaminha esse código inalterado; nos demais casos, segue as regras da tabela abaixo.
400, 401, 403, 404 e 413 são códigos que exigem corrigir a solicitação ou a configuração, enquanto 409, 429 e 5xx são códigos para os quais o cliente deve aguardar e enviar a mesma solicitação novamente.
O formato do corpo do erro varia conforme a especificação, e error.type na rota compatível com Anthropic é definido pelo código de status.
O motivo do 403 é identificado por error.message, enquanto os valores de limite e uso podem ser consultados na tela do console.
Código de status
| Código | Significado | Procedimento |
|---|---|---|
| 400 | O valor da solicitação é inválido. O limite da lista de modelos compatíveis com Anthropic está fora do intervalo de 1 a 1000, ou você tentou continuar o streaming de uma resposta salva usando GET /responses/{responseId}?stream=true. | Corrija o valor para que fique dentro do intervalo. Consulte as respostas salvas sem usar stream. |
| 401 | A chave está ausente ou expirou ou foi revogada. | Verifique o status da chave na tela de chaves da API e confira o nome do cabeçalho e o prefixo Bearer. |
| 403 | Você não tem permissão para acessar o modelo, excedeu o limite de uso, não tem créditos suficientes ou não é o proprietário da voz. | Verifique o motivo em error.message e confira os valores na tela da seção de limites e uso abaixo. |
| 404 | O modelo não existe ou não pode ser acessado com esta chave (incluindo modelos cujo suporte foi encerrado). Também é retornado quando você chama um caminho inexistente ou solicita um resultado do CleviDrive cujo período de retenção de 3 dias foi ultrapassado. | Consulte primeiro a lista de modelos que podem ser chamados usando GET /models. Compare o caminho com a tabela da página Fazer chamadas de API. |
| 408 · 409 · 413 | Tempo limite do upstream, congestionamento ou tamanho da solicitação excedido. O limite de tempo para caminhos de voz é de 5 minutos, e o limite da solicitação é de 28 MiB. | Se houver Retry-After em 409, aguarde esse período e envie a mesma solicitação novamente. Para 413, divida a solicitação antes de enviá-la. |
| 429 | O provedor upstream aplicou uma limitação de taxa. | Se houver Retry-After, aguarde esse período e tente novamente; caso contrário, tente novamente usando backoff exponencial. |
| 5xx | Erro temporário do gateway ou do upstream (incluindo 503). | Tente novamente usando backoff exponencial. Se o problema persistir, entre em contato conosco. |
O código 402 não é retornado. Tanto a falta de créditos quanto o excesso do limite de uso são retornados como 403.
Novas tentativas e contato
O gateway não gera seus próprios erros 429 nem tenta novamente ou enfileira respostas do upstream. O cliente é responsável por aguardar e tentar novamente.
Ao entrar em contato, informe o X-Request-Id em Ajuda e contato. Se você não enviou um X-Request-Id, o valor emitido pelo servidor estará no cabeçalho request-id da resposta compatível com Anthropic.
Corpo do erro
O formato do corpo do erro varia conforme a especificação. Os erros upstream são reorganizados e transmitidos apenas com a mensagem; a pilha e os campos internos não são transmitidos.
Corpo do erro de uma rota compatível com OpenAI.
{
"error": {
"message": "API key is required.",
"type": "invalid_request_error"
}
}Corpo do erro de uma rota compatível com Anthropic. error.type é definido de acordo com o código de status, conforme a tabela abaixo.
{
"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 |
Verificação de limites e uso
Os valores dos limites variam conforme o workspace. Verifique o motivo do status 403 em error.message e, em seguida, consulte os valores na tela a seguir.
| Itens a verificar | Tela do console |
|---|---|
| Limite aplicado ao 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 deduzidos) | Uso |
| Status da chave (se está expirada ou revogada) | Chave de API |