Errors

Todo erro de /v1/* tem o mesmo formato:

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Payment not found.",
    "correlationId": "d815caf8-8fe6-46f2-a1b7-2c135c1e2717"
  }
}

correlationId é sempre o mesmo valor do header de resposta X-Request-Id — sempre inclua esse valor ao reportar um problema pro suporte.

Códigos por status HTTP

Status	`error.code`	Quando
400	`BAD_REQUEST`	Requisição malformada.
400	`VALIDATION_ERROR`	Corpo não passou na validação (campo obrigatório ausente/inválido — `message` lista o(s) motivo(s)).
401	`UNAUTHORIZED`	API key ausente, inválida ou revogada.
403	`FORBIDDEN`	Chave válida, mas sem permissão pra este recurso.
404	`NOT_FOUND`	Recurso não existe (ou não pertence ao seu escopo — nunca vaza que existe pra outro tenant).
409	`CONFLICT`	Estado atual do recurso não permite a operação (ex.: cancelar um pagamento já capturado).
422	`UNPROCESSABLE_ENTITY`	Mesma `Idempotency-Key` usada com um corpo diferente do original.
429	`RATE_LIMITED`	Limite de requisições excedido.
502	`BAD_GATEWAY`	Provider (adquirente/PSP) devolveu algo inesperado.
503	`SERVICE_UNAVAILABLE`	Provider fora do ar.
504	`GATEWAY_TIMEOUT`	Provider não respondeu a tempo.
500	`INTERNAL_ERROR`	Erro nosso — nunca vaza detalhe interno; reporte com o `correlationId`.

Recusa de cartão não é um erro

Uma recusa (declined) é um resultado de negócio, devolvido como 200 OK com status: "failed" no corpo — nunca um 4xx/5xx. Ver Cards.

Erros de rede/provider indeterminados

Um 504 GATEWAY_TIMEOUT (ou 503) numa operação de criação/captura/cancelamento significa que o resultado real é desconhecido — o provider pode ou não ter processado. Nunca tente de novo cegamente sem uma Idempotency-Key: com ela, um retry seu reusa a mesma tentativa em vez de arriscar duplicar (ver Idempotency).