Lumedocs

Erros

Toda resposta de erro tem a mesma forma, para que exista um único caminho de tratamento no seu código.

formato
{
  "code": "INSUFFICIENT_FUNDS",
  "message": "Saldo insuficiente para esta operação.",
  "requestId": "7c3d4b589e21",
  "details": {}
}

A message é sempre segura para exibir ao usuário final: nada de erro de driver, nome de tabela ou caminho de arquivo. O detalhe técnico vai para o log do servidor, ligado a esta resposta pelo requestId.

requestId

Vem no corpo do erro e no cabeçalho X-Request-Id de toda resposta. É o que o suporte pede: ele liga a resposta que você recebeu ao registro do servidor. Guarde-o nos seus próprios logs — sem ele, investigar uma chamada específica vira arqueologia.

Se você enviar um X-Request-Id na requisição, ele é preservado, e a mesma chamada fica rastreável dos dois lados.

Códigos

CódigoHTTPSignificaO que fazer
INVALID_REQUEST400 · 422Corpo malformado, campo desconhecido ou valor inválido.Corrija a requisição. Campo desconhecido é recusado de propósito: “ammount” em vez de “amount” viraria zero em silêncio.
UNAUTHORIZED401Credencial ausente, inválida, revogada, expirada, de outro ambiente ou, numa chave de produção recém-emitida, ainda aguardando a aprovação do banco.Leia a mensagem — ela distingue os seis casos. Numa sessão, renove o token; numa integração, confira a chave e a URL base.
FORBIDDEN403Autenticado, mas sem permissão para esta operação.Não repita. A permissão não vai mudar sozinha. Chave de API em rota que só aceita sessão (cobrança por boleto, TED) cai aqui, e também toda chamada com a chave de uma conta bloqueada ou encerrada.
STEP_UP_REQUIRED403Falta a confirmação de segundo fator para esta operação.Chame POST /v1/auth/step-up com o purpose certo e repita com X-Step-Up.
BIOMETRIC_REQUIRED403Operação de valor alto confirmada só com o código: esta instalação exige também a selfie, conferida contra a biometria cadastrada.Emita a prova de novo em POST /v1/auth/step-up, agora com o campo selfie, e repita a operação com o novo X-Step-Up. A mensagem diz a partir de que valor a regra vale.
NOT_FOUND404O registro não existe — ou não é seu.Transação de outra conta responde 404, e não 403: é o que impede descobrir identificadores por tentativa.
CONFLICT409A operação conflita com o estado atual. A transação já foi decidida, por exemplo.Releia o estado antes de decidir de novo.
IDEMPOTENCY_KEY_REUSED409A mesma chave de idempotência já foi usada com outro conteúdo.Use uma chave nova para uma operação nova. Não reaproveite chave entre pedidos diferentes.
IDEMPOTENCY_IN_FLIGHT409A operação com esta chave ainda está rodando.Espere o que Retry-After indica e repita. A resposta será a da primeira.
INSUFFICIENT_FUNDS422Saldo insuficiente.Confira o saldo disponível: heldCents já saiu do balanceCents.
LIMIT_EXCEEDED422Um limite da conta foi atingido.A mensagem traz o valor que falta. Limites em vigor estão em GET /v1/limits.
APPROVAL_REQUIRED422A operação passa da alçada de aprovação conjunta da conta da empresa: não é executada por quem pediu.Não repita. Repetir dá o mesmo resultado; a operação precisa ficar dentro da alçada.
RATE_LIMITED429Limite de requisições por minuto atingido.Espere o que Retry-After indica. Não repita em laço apertado.
TOO_MANY_ATTEMPTS429Cinco erros de senha ou de código em quinze minutos. No login e na recuperação de senha, a trava é do documento a partir daquela origem (endereço): quem erra não tranca o titular de verdade, que segue entrando de outra origem. Nas etapas já autenticadas, a trava é da própria identidade.Espere o que Retry-After indica. Repetir na hora só prolonga a trava.
PROVIDER_ERROR422 · 503O arranjo de pagamento recusou (422) ou está indisponível (503). Em 503, details.reason pode dizer que nada foi enviado ao banco: LOCATION_REQUIRED (faltou X-Client-Location, que o provedor exige) ou DEVICE_REQUIRED (a sessão foi aberta sem identificar o aparelho).Em 503 sem details.reason, repita com a mesma chave de idempotência. Com LOCATION_REQUIRED, mande a localização e repita; com DEVICE_REQUIRED, entre de novo enviando deviceFingerprint no login. Em 422, confira os dados: repetir dará o mesmo resultado.
DEVICE_NOT_ENABLED403 · 401O aparelho não está habilitado para a conta. 403 no login (POST /v1/auth/mfa): senha e código certos, nenhuma sessão aberta. 401 na renovação e nas rotas autenticadas, quando a instalação impõe a regra e o aparelho da sessão deixou de estar habilitado. details.deviceStatus diz o estado.Não repita, e entrar de novo pelo mesmo aparelho também não resolve: mostre o bloqueio. PENDING aguarda habilitação; BLOCKED só o atendimento libera; UNKNOWN é login sem deviceFingerprint.
CARD_*409 · 422Recusas do cartão: CARD_TERMS_REQUIRED (termo não aceito), CARD_ELIGIBILITY_REQUIRED (análise não aprovada), CARD_KIND_UNAVAILABLE (tipo indisponível), CARD_BLOCKED_BY_INSTITUTION (bloqueado pelo banco), CARD_NOT_ACTIVE (ainda não confirmado pelo emissor), CARD_USE_REVEAL e CARD_USE_SECURE_VIEW (a instalação mostra os dados do cartão pelo outro caminho).Cada rota de /v1/cards diz, na referência, qual destes pode responder e o HTTP de cada um. Conduza o titular ao passo que falta (aceitar o termo, esperar a análise) em vez de repetir.
FEATURE_DISABLED403A funcionalidade está desligada nesta instalação. details.feature diz qual (pix_transfer, billet_issue, subscriptions, merchant_portal…). Cada módulo — assinaturas, portal do estabelecimento, rede de indicação, benefícios — é uma funcionalidade que a instalação liga ou desliga. Não é falta de permissão.Não repita: outra credencial ou outra tentativa dão o mesmo resultado. Consulte GET /v1/features e esconda da tela o que não está ligado.
INTERNAL_ERROR500Erro não previsto do nosso lado.Repita com a mesma chave de idempotência. Se persistir, mande o requestId para o suporte.

O que dá para repetir

Repita 429, 500 e 503 — sempre com a mesma chave de idempotência, e com espera crescente entre as tentativas. Repetir 4xx de validação só produz o mesmo erro mais rápido.

A página de idempotência tem um exemplo de laço de repetição que não cobra duas vezes.