Erros
Saiba como lidar com falhas da API do AI Glot usando códigos de erro estáveis, IDs de solicitação, orientações sobre novas tentativas e explicações com âncoras para cada erro documentado.
Todas as falhas da API usam o mesmo envelope. Use error.code para determinar como agir, nunca a mensagem legível por humanos.
{
"error": {
"type": "permission_error",
"code": "insufficient_scope",
"message": "This credential is missing the batches:write scope.",
"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 | Solicitação malformada ou campo desconhecido | Corrija a solicitaçã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 inexistente ou fora deste espaço de trabalho | Confira o ID e o espaço de trabalho |
| 409 | O estado atual é incompatível com a solicitação | Consulte o recurso e decida o que fazer |
| 413 | Corpo da solicitação grande demais | Envie um corpo menor |
| 422 | Valor bem formado, mas inválido | Corrija o valor indicado |
| 429 | Limite de requisições excedido | Aguarde Retry-After |
| 500/503 | O AI Glot falhou ou está temporariamente indisponível | Tente novamente com espera progressiva |
Códigos de autenticação e permissões
authentication_required
Nenhuma credencial bearer foi enviada. Adicione o cabeçalho Authorization.
invalid_api_key
A chave está malformada ou não é reconhecida. Confira se o valor aig_live_… completo foi copiado.
api_key_expired
A chave atingiu a data de expiração configurada. Crie ou use uma chave substituta.
api_key_revoked
Um administrador revogou ou substituiu esta chave. Atualize a integração com uma credencial ativa.
insufficient_scope
A credencial autenticou, mas não tem o escopo exigido por esta operação.
feature_not_available
O plano do espaço de trabalho ou a versão atual da plataforma não inclui o recurso solicitado.
admin_required
Somente um administrador do espaço de trabalho pode realizar esta operação.
Códigos de solicitação
invalid_request
Não foi possível interpretar a solicitação ou ela não corresponde ao contrato do endpoint.
unknown_field
Uma propriedade do corpo JSON não é reconhecida. Corrija a grafia em vez de desativar a validação. Parâmetros de consulta desconhecidos não geram este erro: eles são ignorados. Portanto, um filtro com erro de digitação retorna um 200 sem filtro.
invalid_parameter
Um parâmetro tem tipo, intervalo ou formato incorreto.
invalid_cursor
O cursor de paginação é inválido. Reutilize next_cursor exatamente como foi retornado.
request_too_large
O corpo da solicitação excede o limite máximo do endpoint.
Códigos de recursos e estado
batch_not_found
Nenhuma tradução visível tem esse ID. Os recursos de outro espaço de trabalho retornam intencionalmente o mesmo erro.
glossary_not_found
Não há glossário para esse par de idiomas.
resource_not_found
O recurso ou a rota solicitada não existe.
glossary_already_exists
Já existe um glossário para esse par de idiomas. Atualize-o em vez de criar outro.
result_not_ready
A tradução ainda não foi concluída, então não é possível baixar o resultado.
batch_not_editable
O estado atual da tradução não permite a alteração de manutenção solicitada.
idempotency_key_reused
A Idempotency-Key já foi usada para outro pedido (outro arquivo, nome ou instrução). Envie o mesmo pedido para repeti-lo, ou uma nova chave para um novo trabalho. Veja Criar uma tradução.
Códigos de arquivo e formato
unsupported_format
A extensão do arquivo não é aceita pelo AI Glot. Consulte Arquivos e formatos para ver todos os formatos e suas extensões.
file_too_large
O arquivo excede o limite para o formato correspondente. Os limites variam conforme o formato, não são globais (60 MB para CSV e 4 MB para um catálogo PO). Por isso, um tamanho aceito para uma extensão pode ser recusado para outra.
file_fetch_failed
Não foi possível obter file_url. A URL precisa usar HTTPS e apontar para o destino final: redirecionamentos não são seguidos, então um link encurtado ou que redirecione após ser assinado falhará aqui.
file_retention_expired
O período de retenção do arquivo enviado terminou e ele não está mais armazenado. Crie a tradução novamente usando o arquivo de origem.
file_expired
O arquivo associado a esta tradução não está mais disponível, então não é possível prosseguir com a operação.
result_too_large
A tradução concluída excede o tamanho máximo que pode ser retornado. Divida o arquivo de origem e traduza-o em partes.
Códigos de plano e aprovação
plan_invalid
Não foi possível transformar a instrução ou o refinamento em um plano utilizável. Nenhuma cobrança foi feita. Quando a causa é conhecida, a mensagem informa o motivo: nada no arquivo correspondia à instrução, a instrução pede para escrever em um local que o arquivo não comporta ou não foi possível gerar o plano desta vez (envie a mesma instrução novamente). Caso contrário, reformule-a: indicar os campos ou as colunas a traduzir é mais confiável do que descrevê-los.
plan_changed
O expected_plan_revision enviado não corresponde ao plano atual disponível para revisão, ou não foi possível verificar essa revisão. Esta aprovação não iniciou um novo trabalho. Leia o lote novamente, confira o escopo atual, as exclusões e o custo calculado e decida se deseja aprovar usando a nova revisão. Não tente aprovar novamente, sem conferir, com a revisão antiga.
no_plan_yet
A aprovação foi solicitada antes da criação de um plano. Primeiro, chame POST /v1/batches/{batch_id}/plan. Essa verificação impede que uma integração cobre do espaço de trabalho por uma tradução que ninguém especificou.
batch_not_awaiting_approval
A tradução não está em um estado que permita aprovação; geralmente, ela já está em andamento ou foi concluída. Consulte GET /v1/batches/{batch_id} em vez de aprovar novamente.
insufficient_credits
O saldo do espaço de trabalho não cobre o custo calculado do plano (HTTP 402). Nenhum crédito foi reservado, então será possível aprovar a tradução quando forem adicionados créditos.
O erro inclui um objeto payment, tanto na API REST quanto na ferramenta MCP approve_translation:
"payment": {
"credits_needed": 30000,
"credit_balance": 5000,
"credits_missing": 25000,
"credits_to_buy": 25000,
"price_eur": 25,
"payment_url": "https://app.ai-glot.com/w/<workspace_id>/new?continue=<batch_id>&pay=1",
"plans": [
{ "plan": "Starter", "eur_per_month": 42, "credits_per_month": 100000 },
{ "plan": "Pro", "eur_per_month": 199, "credits_per_month": 1000000 }
]
}credits_to_buy é a menor compra que cobre a diferença (aplica-se o valor mínimo de compra). payment_url abre esta tradução no AI Glot com a janela de compra já aberta: com o valor exato, os pacotes de créditos, os planos e a amostra grátis, caso o espaço de trabalho seja elegível. O link só funciona para um membro conectado ao espaço de trabalho, portanto, é seguro compartilhá-lo. plans lista os planos mensais, que oferecem um custo por crédito menor para quem traduz regularmente; eles também aparecem na mesma página, abaixo da opção de compra única.
Um agente deve perguntar ao usuário antes de oferecer o link, nunca pagar em nome dele e, após o pagamento, conferir o saldo com GET /v1/account e aprovar novamente quando o usuário confirmar. O usuário também pode iniciar a tradução nessa página.
Códigos de idioma e glossário
language_not_supported
A etiqueta não faz parte do catálogo de idiomas aceitos. Consulte GET /v1/languages.
invalid_language_pair
Não é possível dividir o identificador do par de idiomas em duas etiquetas BCP 47 aceitas.
glossary_term_limit_reached
A quantidade de termos resultante ultrapassaria o limite do plano do espaço de trabalho. A atualização é atômica; nada foi alterado.
glossary_limit_reached
O espaço de trabalho atingiu o número máximo de glossários permitido pelo plano atual.
invalid_glossary_terms
Uma ou mais entradas do glossário estão vazias, incompletas ou são inválidas por outro motivo.
Códigos de serviço
rate_limited
A credencial excedeu o limite de uma janela de requisições. Aguarde Retry-After e tente novamente com um atraso aleatório.
internal_error
O AI Glot falhou inesperadamente. Tente novamente com espera progressiva e mantenha o request_id.
service_unavailable
Um serviço necessário está temporariamente indisponível. Tente novamente com espera progressiva.