# Tratamento de Erros da API — Tipos de Erro, Códigos e doc_url

> Todo erro da v1 é um objeto JSON com type, code, message e doc_url — esta página documenta a taxonomia completa de tipos de erro e cada código de erro individual, e é exatamente o que um doc_url retornado referencia.

Toda requisição v1 com falha — toda resposta não-2xx — retorna a mesma estrutura JSON, listada abaixo na íntegra. Esta página também é o que o `doc_url` de cada erro referencia: cada código tem sua própria seção ancorada, então seguir um `doc_url` de uma resposta de erro real leva você diretamente à explicação daquele código exato.

## A estrutura do erro

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "missing_parameter",
    "message": "A required parameter is missing.",
    "doc_url": "https://imagetotable.ai/developers/guides/errors#missing_parameter",
    "param": "file"
  }
}
```

- `type` — a categoria ampla na qual este erro se enquadra (veja a tabela abaixo). Útil para ramificações genéricas no seu código de tratamento de erros ("isto é um problema de autenticação ou de validação") sem verificar cada `code` individual.
- `code` — o identificador de erro específico e estável. É nele que você deve basear suas comparações no código — ele não mudará mesmo se a redação do `message` for melhorada posteriormente.
- `message` — uma explicação legível para humanos. Útil para logs e depuração, não deve ser interpretada programaticamente.
- `doc_url` — um link direto para a seção desta página referente àquele `code` exato.
- `param` — presente apenas em erros do tipo validação (`missing_parameter`, `invalid_parameter`, `duplicate_field_name`), nomeando o campo específico da requisição que causou o erro. Omitido completamente — não `null` — quando não aplicável.

## Tipos de erro

Cada `code` pertence exatamente a um `type`:

| Tipo | Significado |
| --- | --- |
| authentication_error | Algo está errado com a forma como você autenticou a requisição (ou se a autenticou). |
| invalid_request_error | A requisição em si está malformada — um parâmetro ausente ou inválido. |
| not_found_error | O recurso referenciado na URL (um ID de documento, lote ou modelo) não existe ou não pertence à sua conta. |
| insufficient_credits | Sua conta não tem créditos suficientes para realizar a ação (paga) solicitada. |
| rate_limit_error | Você excedeu a taxa de requisições para esta categoria de endpoint — consulte Limites de Taxa . |
| internal_error | Algo deu errado em nosso lado, não no seu. |

## Um caso especial: `processing_error`

`processing_error` **não** é um `type` que você verá em uma resposta de nível superior `{"error": ...}`. Ele nunca faz com que uma chamada de API falhe por si só. Em vez disso, descreve um único documento dentro de um lote que não pôde ser extraído — você o verá refletido como `"status": "failed"` naquele documento dentro de uma resposta `GET /batches/{batch_name}/results` que, de outra forma, retorna 200 OK, junto com outros documentos no mesmo lote que foram processados com sucesso. Não trate uma falha no nível do documento dentro de uma chamada de API bem-sucedida como um erro para repetir o lote inteiro — verifique o `status` de cada documento individualmente.

## Códigos de erro

### missing_api_key

**Tipo:** `authentication_error` · **Código HTTP:** 401

Nenhuma chave de API foi fornecida. Envie-a como `Authorization: Bearer <key>`.

### invalid_api_key

**Tipo:** `authentication_error` · **Código HTTP:** 401

A chave de API fornecida é inválida ou a conta à qual ela pertence está desativada.

### plan_required

**Tipo:** `authentication_error` · **Código HTTP:** 403

A API não está disponível no plano Free. Faça upgrade para Basic ou superior para usá-la.

### missing_parameter

**Tipo:** `invalid_request_error` · **Código HTTP:** 400

Um parâmetro obrigatório está faltando. Verifique `param` no objeto de erro para identificar qual.

### invalid_parameter

**Tipo:** `invalid_request_error` · **Código HTTP:** 400

Um parâmetro tem um valor inválido. Verifique `param` e `message` para obter detalhes — este é um código genérico que cobre desde uma string `crop` malformada até um `limit` fora do intervalo ou um lote sem itens elegíveis para processamento.

### duplicate_field_name

**Tipo:** `invalid_request_error` · **Código HTTP:** 400

Um campo com este nome já existe neste modelo. Os nomes dos campos devem ser únicos dentro de um modelo.

### idempotency_key_reused

**Tipo:** `invalid_request_error` · **Código HTTP:** 400

Este `Idempotency-Key` já foi usado para uma solicitação com parâmetros diferentes. Use uma nova chave para uma solicitação genuinamente diferente — consulte [Idempotência](/developers/guides/idempotency) para o comportamento completo.

### document_not_found

**Tipo:** `not_found_error` · **Código HTTP:** 404

Nenhum documento foi encontrado com o ID fornecido (ou ele não existe, ou não pertence à sua conta).

### batch_not_found

**Tipo:** `not_found_error` · **Código HTTP:** 404

Nenhum lote foi encontrado com o nome fornecido.

### template_not_found

**Tipo:** `not_found_error` · **Código HTTP:** 404

Nenhum modelo foi encontrado com o ID fornecido.

### insufficient_credits

**Tipo:** `insufficient_credits` · **Código HTTP:** 402

Créditos insuficientes para realizar esta ação. Verifique `GET /account` para saber seus `available_credits` atuais antes de tentar novamente.

### rate_limit_exceeded

**Tipo:** `rate_limit_error` · **Código HTTP:** 429

Muitas requisições. Reduza a velocidade e tente novamente após o período de reinicialização — consulte o cabeçalho de resposta `X-RateLimit-Reset` e o guia de [Limites de Taxa](/developers/guides/rate-limits).

### internal_error

**Tipo:** `internal_error` · **Código HTTP:** 500

Ocorreu um erro inesperado. Se isso persistir, o problema é nosso, não seu — se você conseguir reproduzi-lo de forma confiável, essa é uma informação útil para incluir se você entrar em contato conosco.

---

Source: https://imagetotable.ai/pt/developers/guides/errors