> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ticto.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Erros

> Referência completa de códigos de status HTTP e slugs de erro da Ticto API v2, com o formato do envelope de erro e exemplos de validação.

Todos os erros da Ticto API v2 seguem um envelope JSON consistente, com um **slug estável e legível por máquina** no campo `error` e uma **mensagem em linguagem natural** no campo `message`. Isso facilita o tratamento programático de erros sem depender de textos que podem mudar entre versões.

## Formato do envelope de erro

```json theme={null}
{
  "error": "validation_failed",
  "message": "The request payload is invalid.",
  "request_id": "req_a1b2c3",
  "details": [
    "The name field is required.",
    "The price must be at least 500."
  ]
}
```

| Campo | Tipo | Descrição |
| - | - | - |
| `error` | `string` | Slug estável e machine-readable que identifica o tipo do erro. Use este campo na lógica de tratamento. |
| `message` | `string` | Mensagem legível (em inglês) para exibição ou logs. Pode mudar sem aviso prévio, então **não programe contra ela**. |
| `request_id` | `string \| null` | Eco do header `X-Request-Id` que você enviou. Informe ao suporte para diagnóstico rápido. `null` se você não enviou o header. |
| `details` | `array` | Lista de mensagens de validação (strings), uma por regra que falhou. Presente apenas no erro `422 validation_failed`. Ausente nos demais erros. |

## Códigos HTTP

| Status | Slug (`error`) | Quando ocorre |
| - | - | - |
| `201` | — | Recurso criado com sucesso |
| `400` | `idempotency_key_required` | `POST` sem o header `Idempotency-Key` |
| `401` | `unauthorized` | Token ausente, inválido ou expirado |
| `403` | `insufficient_scope` | Token não possui o escopo exigido pela rota |
| `404` | `not_found` | Recurso não encontrado ou que não pertence à sua conta |
| `422` | `validation_failed` | Payload inválido — detalhes no array `details` |
| `429` | — | Rate limit atingido. Corpo `{ "message": "Too Many Attempts." }` + header `Retry-After` (não usa o envelope `error`) |
| `503` | `upstream_unavailable` | Motor de relatórios (endpoints de leitura) temporariamente indisponível |

<Note>
  Reenviar uma escrita com a mesma `Idempotency-Key` **não** gera erro: a API devolve a resposta original com o header `Idempotent-Replay: true` (veja [Idempotência](/concepts/idempotency)). Erros do canal interno na escrita são repassados (`400`/`404`/`422`); indisponibilidade do motor de escrita retorna `502` com `error: upstream_error`.
</Note>

<Note>
  O slug `error` é estável e legível por máquina, então programe sua lógica de tratamento de erro contra ele. O campo `message` pode mudar sem aviso e não deve ser usado como base para decisões programáticas.
</Note>

<Tip>
  Em caso de erro, sempre logue o `request_id`. Ele acelera o diagnóstico quando você entrar em contato com o suporte da Ticto.
</Tip>

## Erros de validação

Quando a API retorna `422 validation_failed`, o campo `details` traz um array de **mensagens de texto**, uma por regra de validação que falhou (o mesmo formato do validador do Laravel).

### Exemplo com múltiplos erros

```json theme={null}
{
  "error": "validation_failed",
  "message": "The request payload is invalid.",
  "request_id": "req_d4e5f6",
  "details": [
    "The name field is required.",
    "The price must be at least 500.",
    "The type field is required."
  ]
}
```

Itere sobre o array `details` para exibir as mensagens ao usuário ou registrar o que precisa ser corrigido antes de reenviar a requisição.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.