Erros

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

{
  "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

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). Erros do canal interno na escrita são repassados (400/404/422); indisponibilidade do motor de escrita retorna 502 com error: upstream_error.

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.

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

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

{
  "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.

Introdução

Autenticação

Conceitos

Guias

Formato do envelope de erro

Códigos HTTP

Erros de validação

Exemplo com múltiplos erros

​Formato do envelope de erro

​Códigos HTTP

​Erros de validação

​Exemplo com múltiplos erros

Formato do envelope de erro

Códigos HTTP

Erros de validação

Exemplo com múltiplos erros