Erros

Toda resposta de erro da Ligga API segue a RFC 7807, Problem Details for HTTP APIs: Content-Type: application/problem+json e um corpo com os mesmos campos, qualquer que seja o endpoint. Esta página descreve esse corpo e lista o catálogo inteiro de erros.

Formato

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/problem+json
X-Request-Id: req_9f2c1a7b4d8e4f0a91c3b5d7e2f40a68

{
  "type": "https://api.ligga.app/errors/validation",
  "title": "Validation failed",
  "status": 422,
  "detail": "Request body failed schema validation",
  "instance": "/v1/customers",
  "request_id": "req_9f2c1a7b4d8e4f0a91c3b5d7e2f40a68",
  "errors": [
    { "field": "email", "code": "invalid_email", "message": "Formato de e-mail inválido" },
    { "field": "phone", "code": "required_when_email_null", "message": "Telefone obrigatório quando o e-mail não é informado" }
  ]
}

Campo	Presença	Descrição
type	sempre	URL que identifica o erro. É por ela que você decide o que fazer
title	sempre	Rótulo curto em inglês, para leitura humana
status	sempre	O mesmo código HTTP da resposta
request_id	sempre	Identificador da requisição nos registros da Ligga
detail	quando aplicável	Frase que explica o caso concreto
instance	quando aplicável	Caminho que produziu o erro
errors	em validation	Lista de campos recusados, um item por campo

Cuidado

O campo é type, não code. O corpo do erro não tem campo code no primeiro nível: o que aparece como code está dentro de cada item de errors, e diz respeito a um campo do corpo, não ao erro como um todo.

O valor de type é a URL https://api.ligga.app/errors/ seguida do código da tabela abaixo. São identificadores estáveis: mudam de significado nunca, e não precisam abrir uma página no navegador. Decida por type, nunca por title, que é texto e pode ser reescrito.

request_id

request_id repete o valor do cabeçalho X-Request-Id, que acompanha toda resposta da API, com erro ou sem. É esse valor que o suporte da Ligga pede para investigar um caso. Registre-o junto com as suas próprias falhas; sem ele, a única forma de localizar a requisição é adivinhar por horário.

Se você já tem um identificador de correlação, pode enviá-lo em X-Request-Id na requisição: até 128 caracteres entre letras, números, _ e - são reaproveitados na resposta e nos registros.

Catálogo de erros

Estes são todos os erros que a API produz. O código na coluna type é o sufixo da URL: insufficient_scope corresponde a https://api.ligga.app/errors/insufficient_scope.

HTTP	type	Quando acontece	O que fazer
401	invalid_token	O cabeçalho Authorization está ausente ou malformado, ou a chave não existe	Envie Authorization: Bearer $LIGGA_API_KEY e confira o valor da chave
401	token_revoked	A chave foi revogada	Peça uma chave nova ao time da Ligga e substitua a antiga
401	token_expired	A chave passou da data de expiração	Peça uma chave nova ao time da Ligga
403	insufficient_scope	A chave não carrega o escopo da operação, ou o plano libera apenas leitura	Confira scopes em GET /v1/me e peça o escopo que falta
403	api_disabled	A conta ainda não teve a API habilitada	Fale com o time da Ligga para habilitar a API na conta
403	module_not_enabled	O recurso depende de um módulo que não está no contrato	Confira modules em GET /v1/me e contrate o módulo
403	ip_not_allowed	A chave restringe IPs e a requisição veio de fora da lista	Chame de um IP da lista, ou peça o ajuste da lista
404	not_found	O registro não existe ou pertence a outra conta	Confira o {id} do caminho; não repita a chamada
409	idempotency_conflict	A mesma Idempotency-Key já foi usada com outra requisição	Gere uma chave nova. Ver Idempotência
422	validation	Corpo, filtro, ordenação ou cursor fora do contrato	Leia errors e detail, corrija a requisição; repetir sem mudar dá o mesmo erro
429	rate-limit-exceeded	Uma das janelas de limite estourou	Aguarde o Retry-After. Ver Limites de requisições
500	internal_error	Falha inesperada do lado da Ligga	Tente de novo com espera crescente; se persistir, envie o request_id ao suporte
503	service_unavailable	Uma dependência da API está indisponível	Tente de novo com espera crescente

Nota

A lista acima é fechada. Se o seu código espera unauthorized, rate_limited, validation_failed ou idempotency_key_mismatch, ele está tratando erros que a API não emite — nenhum switch vai cair nesses ramos.

Erros de validação

O 422 é o único que traz errors. Cada item aponta um campo e o motivo da recusa:

Campo do item	Descrição
field	Nome do campo recusado, como aparece no corpo da requisição
code	Motivo em forma de identificador, estável para o seu código
message	Frase em português, pronta para mostrar a quem preencheu o formulário

Quando o 422 vem de um parâmetro de query, como um cursor corrompido, um campo de ordenação desconhecido ou um operador de filtro inexistente, não há errors: o parâmetro recusado aparece em detail.

O que a API nunca devolve

Erros internos passam por sanitização antes de virar resposta. A API não expõe:

• mensagens brutas do banco, código de estado SQL ou nome de restrição;
• pilha de chamadas;
• identificadores de registros que pertencem a outra conta.

Quando detail vem genérico, o detalhe real ficou nos registros da Ligga, indexado pelo request_id.

Como tratar no cliente

• Decida por type. title e detail são texto e podem mudar sem aviso.
• Não repita 4xx sem mudar a requisição: o resultado será o mesmo. As exceções são 429, que pede espera, e 409, que pede uma chave nova.
• Repita 5xx com espera crescente entre as tentativas, e um teto de tentativas.
• Em 429, respeite Retry-After em vez de escolher o próprio intervalo.
• Em validation, mostre errors[*].message a quem preencheu o formulário; o texto já vem em português.
• Registre request_id em toda falha. É o que torna um chamado de suporte respondível.

Veja também

• Autenticação — o que causa os erros 401 e 403
• Limites de requisições — o 429 em detalhe
• Idempotência — o 409 em detalhe
• Paginação, filtros e ordenação — os parâmetros que caem em 422