Erros

A API devolve este envelope em toda falha:

{
  "status": "error",
  "message": "Pedido não encontrado"
}

O corpo de sucesso não carrega o campo status. Ele traz o dado direto.
Exceção: no 422, o campo status pode faltar. Veja a seção seguinte.

Falha de validação

O código é 422 e o corpo ganha um campo a mais, com um array de mensagens por campo:

{
  "status": "error",
  "message": "The given data was invalid.",
  "errors": {
    "amount": ["Expected number, received string"],
    "term": ["Prazo mínimo de 1 mês"]
  }
}

Trate errors como mapa de campo para lista. Um campo pode acumular mais de uma mensagem.

No 422, o contrato garante apenas os campos message e errors. O campo status pode
faltar. Não exija status ao tratar o 422.

Códigos que você precisa tratar

As rotas atuais devolvem 401, 403, 422, 429 e 503. Os demais códigos valem para
rotas futuras.

Código	Quando acontece	O que fazer
`400`	A requisição está malformada.	Corrija a chamada. Não repita igual.
`401`	O token está ausente, expirado ou inválido.	Peça um token novo e repita uma vez.
`403`	O token é válido, mas não tem permissão para a operação.	Não repita. Confira o escopo da credencial.
`404`	O recurso não existe ou não pertence a você.	Não repita. Veja a nota abaixo.
`409`	Conflito de estado. O corpo traz `"Conflict."`.	Leia o recurso antes de repetir.
`422`	A validação recusou o corpo.	Corrija os campos listados em `errors`.
`429`	Você passou do limite de chamadas.	Espere e repita com recuo exponencial.
`500`	Falha interna. O corpo traz `"Did something wrong happen"`.	Repita com recuo. Se persistir, escreva para tecnologia@77sol.com.br.
`502`	Erro de gateway.	Repita com recuo.
`503`	Um serviço de apoio está fora.	Repita com recuo.
`504`	O gateway não recebeu resposta a tempo.	Repita com recuo.

A nota importante sobre 404

A API responde 404, e não 403, quando o recurso existe mas pertence a outro parceiro.
Esse comportamento é deliberado: um 403 revelaria que o identificador existe.

Logo, 404 significa "não existe para você". Não conclua que o recurso foi apagado.

Rota inexistente

Uma URL desconhecida devolve 404 com a mensagem no formato do método e do caminho:

{
  "status": "error",
  "message": "Route GET /api/v1/naoexiste not found"
}

Como repetir a chamada

Repita apenas 429, 500, 502, 503 e 504. Use recuo exponencial com jitter
(espera extra aleatória em cada tentativa): 1 s, 2 s, 4 s, 8 s, com teto de cinco tentativas.

Nunca repita 400, 401 sem token novo, 403, 404, 409 ou 422. A resposta não muda.

Falha de validação#

Códigos que você precisa tratar#

A nota importante sobre 404#

Rota inexistente#

Como repetir a chamada#

Falha de validação

Códigos que você precisa tratar

A nota importante sobre 404

Rota inexistente

Como repetir a chamada