---
title: "Erros"
description: "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."
canonical: "https://ai-glot.com/docs/pt/api/errors"
updated: "2026-08-12"
---

# Erros

Toda falha de API utiliza um envelope único. Baseie sua lógica no `error.code`, nunca na mensagem legível para humanos.

```json title="Exemplo de erro"
{
  "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            |

**Corrija antes de tentar novamente**

A maioria das respostas 400, 401, 403, 404, 409, 413 e 422 exige a alteração de uma credencial, identificador, estado ou requisição.

**Tente novamente com segurança**

Tente novamente o erro 429 após o `Retry-After`; tente 500 e 503 com backoff exponencial e jitter aleatório.

> **Note**
>
> Mantenha o `request_id` nos logs e mensagens de suporte. Ele identifica a requisição no servidor sem expor sua chave de API ou o conteúdo do CSV.

## 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`](/docs/api/languages/list).

### 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.