Erros
Gerencie falhas da API do AI Glot usando códigos de erro estáveis, IDs de requisição, orientações de tentativa e explicações detalhadas para cada erro documentado.
Toda falha de API utiliza um envelope único. Baseie sua lógica no error.code, nunca na mensagem legível para humanos.
{
"error": {
"type": "permission_error",
"code": "insufficient_scope",
"message": "Esta credencial não possui o escopo batches:write.",
"docs_url": "https://ai-glot.com/docs/api/errors#insufficient_scope"
},
"request_id": "req_example"
}Códigos de status
| Status | Significado | O que fazer |
|---|---|---|
| 400 | Requisição malformada ou campo desconhecido | Corrija a requisição |
| 401 | Credencial ausente, inválida, expirada ou revogada | Substitua ou renove a credencial |
| 403 | Autenticado, mas sem permissão | Conceda o escopo ou recurso necessário |
| 404 | Recurso ausente ou fora deste workspace | Verifique o ID e o workspace |
| 409 | Estado atual conflita com a requisição | Leia o recurso e decida a ação |
| 413 | Corpo da requisição muito grande | Envie um corpo menor |
| 422 | Formato correto, mas valor inválido | Corrija o valor indicado |
| 429 | Limite de taxa excedido | Aguarde o Retry-After |
| 500/503 | Falha no AI Glot ou indisponibilidade temporária | Tente novamente com backoff |
Códigos de autenticação e permissão
authentication_required
Nenhuma credencial bearer foi enviada. Adicione o cabeçalho Authorization.
invalid_api_key
A chave está malformada ou é desconhecida. Verifique se todo o valor aig_live_… foi copiado.
api_key_expired
A chave atingiu a data de expiração configurada. Crie ou use uma substituta.
api_key_revoked
Um administrador revogou ou rotacionou esta chave. Atualize a integração com uma credencial ativa.
insufficient_scope
A credencial foi autenticada, mas não possui o escopo exigido por esta operação.
feature_not_available
O plano do workspace ou a versão atual da plataforma não inclui o recurso solicitado.
admin_required
Apenas um administrador do workspace pode realizar esta operação.
Códigos de requisição
invalid_request
A requisição não pode ser processada ou não corresponde ao contrato do endpoint.
unknown_field
Uma propriedade do corpo JSON não foi reconhecida. Corrija a ortografia em vez de remover a validação. Parâmetros de query não reconhecidos nunca geram este erro; eles são ignorados, portanto, um filtro digitado incorretamente retorna um 200 sem filtros.
invalid_parameter
Um parâmetro possui tipo, intervalo ou formato incorreto.
invalid_cursor
O cursor de paginação é inválido. Reutilize o next_cursor exatamente como foi retornado.
request_too_large
O corpo da requisição excede o limite rígido do endpoint.
Códigos de recurso e estado
batch_not_found
Nenhuma tradução visível possui este ID. Recursos em outro workspace retornam intencionalmente o mesmo erro.
glossary_not_found
Não existe um glossário para esse par de idiomas.
resource_not_found
O recurso ou rota solicitada não existe.
glossary_already_exists
Já existe um glossário para este par de idiomas. Atualize-o em vez de criar outro.
result_not_ready
A tradução ainda não foi concluída, portanto, o resultado ainda não pode ser baixado.
batch_not_editable
O estado atual da tradução não permite a alteração de manutenção solicitada.
Códigos de idioma e glossário
language_not_supported
A tag está fora do catálogo suportado. Consulte GET /v1/languages.
invalid_language_pair
O identificador do par de idiomas não pode ser dividido em duas tags BCP 47 suportadas.
glossary_term_limit_reached
A contagem resultante de termos excederia a cota do plano do workspace. A atualização é atômica; nada foi alterado.
glossary_limit_reached
O workspace atingiu o limite de glossários para o plano atual.
invalid_glossary_terms
Uma ou mais entradas do glossário estão vazias, incompletas ou inválidas.
Códigos de serviço
rate_limited
A credencial excedeu a janela de taxa. Aguarde o Retry-After e tente novamente com jitter.
internal_error
O AI Glot falhou inesperadamente. Tente novamente com backoff e mantenha o request_id.
service_unavailable
Um serviço necessário está temporariamente indisponível. Tente novamente com backoff.