Pular para o conteúdo
LiggaLiggaLigga API

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

Seção intitulada “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

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

Seção intitulada “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

Seção intitulada “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 data.api.modules em GET /v1/team 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
409 resource_conflict O estado atual impede a operação: valor acima do saldo, fatura fechada, dependência ativa ou alteração financeira por uma rota antiga Consulte o recurso e use a operação de recebimento, baixa, estorno ou cancelamento correspondente. Repetir o mesmo corpo não resolve o conflito
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

Erros de validação

Seção intitulada “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

Seção intitulada “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

Seção intitulada “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

Seção intitulada “Veja também”

Código no GitHubEspecificação OpenAPIllms.txt