Erros - OriPay API

Todo erro da API tem o mesmo formato:

{
  "error": {
    "code": "validation_error",
    "message": "Requisição inválida.",
    "request_id": "0f6b1c9e-6a1d-4c8e-9a7b-2d3e4f5a6b7c",
    "details": [{ "field": "amount", "issue": "Number must be greater than or equal to 1" }]
  }
}

Decida pelo code, nunca pelo message (o texto pode mudar).
request_id é o mesmo valor do header X-Request-ID. Mande ao suporte.
Campos extras aparecem só em alguns códigos: details em validation_error, existing_id em external_id_conflict.

Códigos da API

HTTP	`code`	Quando	Repetir?
400	`validation_error`	Corpo, query ou `Idempotency-Key` inválidos, ou campo desconhecido no corpo. `details` lista `field` e `issue` quando o problema é de campo	Não, corrija
400	`idempotency_key_required`	Criação sem `Idempotency-Key`	Não, corrija
401	`invalid_api_key`	Chave ausente, errada, revogada ou ainda aguardando aprovação	Não
403	`https_required`	Chamada feita por HTTP	Não, use HTTPS
403	`account_not_approved`	A conta não está aprovada para operar	Não
403	`ip_not_allowed`	IP fora da lista da chave	Não
403	`insufficient_scope`	Chave sem a permissão	Não
404	`not_found`	Recurso não existe nesta conta	Não
409	`external_id_conflict`	`external_id` já usado com outra `Idempotency-Key`; traz `existing_id` (pode ser `null` se o primeiro ainda está em andamento)	Não
409	`request_in_progress`	A mesma `Idempotency-Key` ainda está processando	Sim, mesma chave
409	`event_pending`	Reenvio de um evento que ainda está na fila	Espere a entrega
413	`payload_too_large`	Corpo maior que 64 KB	Não
422	`idempotency_key_reused`	`Idempotency-Key` repetida com corpo diferente ou com outro `external_id`	Não
422	`refund_amount_exceeds_received`	Devolução maior que o `refundable_amount`	Não
429	`rate_limited`	Muitas chamadas. Ver Limites	Sim, depois
500	`internal_error`	Erro nosso	Sim, mesma chave

Em POST /v1/pix/received/{id}/refunds, um {id} que não é um PIX recebido da conta pode voltar como not_found com HTTP 422.

Códigos repassados da operação PIX

Recusas de negócio da operação (saldo, limite, chave de destino, banco) chegam no mesmo formato, com o code e o HTTP originais quando o HTTP é menor que 500. Indisponibilidade do banco chega como 503 com o code original. Exemplos comuns:

HTTP	`code`	Quando	Repetir?
422	`insufficient_balance`	Saldo não cobre a operação	Não
422	`velocity_limit_exceeded`	Passou do limite PIX da janela atual	Depois da janela
422	`provider_limit_exceeded`	O banco recusou por limite	Não
404 / 422	`pix_key_not_found`	Chave PIX de destino não existe	Não
422	`recipient_blocked`	Destino bloqueado pelo antifraude	Não
422	`devolution_window_expired`	Passou o prazo para devolver o PIX	Não
503	`provider_unavailable`	Banco indisponível	Sim, mesma chave

Trate qualquer code desconhecido pelo HTTP: 4xx não repita sem corrigir; 503 e 500 repita com a mesma Idempotency-Key.

Antifraude em transferências e devoluções

POST /v1/pix/transfers e POST /v1/pix/received/{id}/refunds passam pelo motor de risco depois da autenticação e antes da validação do corpo. Estas respostas usam um formato próprio, sem o objeto error.code:

HTTP	Corpo	Quando	Repetir?
403	`{ "error": "risk_score_exceeded" }`	O antifraude bloqueou a operação	Não. Fale com a OriPay
401	`{ "code": "step_up_required_risk_unavailable" }`	O antifraude está fora do ar e o valor passa de R$ 1.000,00	Sim, depois, mesma chave