Erros e boas práticas
Formato dos erros
Erros vêm com um status HTTP e um corpo JSON com a mensagem em error:
JSON
{ "error": "Company not found" }
Alguns endpoints adicionam detalhes, como details (erros de validação por campo). Trate error como texto para logs e suporte, não como código fixo: as mensagens podem mudar.
| Status | Quando acontece | O que fazer |
|---|---|---|
400 |
JSON malformado. | Corrija o corpo da requisição. |
401 |
Credenciais ausentes ou inválidas. | Confira X-Client-Id e X-Client-Secret. |
403 |
Funcionalidade não liberada para a sua empresa, ou recusa da instituição de pagamento ao enviar um Pix. | Fale com o time marx ou verifique os dados do Pix. |
404 |
Recurso não encontrado ou de outra empresa. | Confira o identificador. |
409 |
Requisição com a mesma Idempotency-Key ainda em processamento (Pix Automático). |
Aguarde e tente de novo. |
422 |
Dados inválidos ou operação não permitida no estado atual. | Leia error, corrija e reenvie. |
429 |
Limite de requisições atingido (página de pagamento e painel). | Espere e tente de novo com intervalo. |
5xx / 502 |
Falha temporária nossa ou da rede bancária. | Repita com espera crescente (veja abaixo). |
Repetindo requisições com segurança
Redes falham. Antes de repetir uma criação, garanta que ela não vai gerar duplicidade:
| Recurso | Proteção contra duplicidade |
|---|---|
| Repasses | Envie sempre um reference único. Repetir o mesmo reference devolve o repasse já criado (200), sem novo envio de dinheiro. |
| Pix Automático | Envie o cabeçalho Idempotency-Key em POST/PATCH (veja abaixo). Assinaturas também deduplicam por reference. |
| Devoluções | O cancelid é único por cobrança: repetir o mesmo devolve a devolução existente. |
| Cobranças | Sem deduplicação automática. Use um reference seu e, se ficar em dúvida após um erro de rede, consulte antes de criar outra. |
Idempotency-Key (Pix Automático)
HTTP
POST /api/pix_automatico/subscriptions
Idempotency-Key: 6b1f5c1e-assinatura-cliente-42
- Até 255 caracteres; use um UUID ou um identificador estável do seu lado. Vale por 7 dias e é separado por empresa.
- Mesma chave e mesmo corpo: a resposta original é devolvida com o cabeçalho
Idempotent-Replayed: true. - Mesma chave com corpo diferente:
422. - Chave ainda em processamento:
409. - Se a requisição terminar em erro, a chave é liberada e você pode tentar de novo com ela.
Espera entre tentativas
Para 429, 5xx e falhas de rede, tente de novo com espera exponencial e um pouco de aleatoriedade (por exemplo 1s, 2s, 4s, 8s, até 5 tentativas). Não repita 4xx sem corrigir a requisição.
Checklist de produção
- [ ] Credenciais guardadas em cofre ou variáveis de ambiente, nunca no front-end.
- [ ] Webhook em HTTPS, respondendo
2xxrápido (menos de 5 segundos). - [ ] Assinatura HMAC dos webhooks ativada e validada.
- [ ] Processamento de webhooks idempotente (use
X-Marx-Event-Id). - [ ]
referencepróprio em todas as cobranças e repasses, para conciliar. - [ ] Decisões baseadas em
lifecycle_status, não no texto de mensagens. - [ ] Alertas para picos de
401,403e5xx.