Referência de erros (API merchant)
Envelope JSON típico:
{
"error": {
"code": "VALIDATION_FAILED",
"message": "Idempotency-Key is required.",
"request_id": "..."
}
}Os códigos abaixo são os códigos HTTP de envelope que o runtime devolve. Não trate códigos internos de domínio (PAYIN_*) como contrato HTTP estável — o handler de create mapeia vários deles para VALIDATION_FAILED.
Autenticação — 401 AUTH_REQUIRED
Credencial em falta, malformada, desconhecida ou revogada. Mensagem típica: Authentication required.
Autorização — 403 AUTH_FORBIDDEN
Credencial válida a aceder a outro merchant, sem capacidade, ou fluxo recusado (autorização/risco). Mensagem típica: Forbidden.
CSRF inválido em sessão cookie também é 403 AUTH_FORBIDDEN.
Validação — 400 VALIDATION_FAILED
Exemplos de mensagens reais (lista não exclusiva):
Idempotency-Key is required.Invalid pay-in intent payload.Invalid merchant uuid./Invalid UUID.expires_at is invalid.Pay-in intent expiresAt must be in the future.Pay-in idempotency key was reused with a different payload.pay-in expected amount is invalid.Invalid status filter./Invalid asset filter.Invalid limit parameter./Invalid offset parameter.Unexpected field.jurisdiction is invalid.
Asset/rail não representável nos decimais do token, metadata técnica em falta e amount inválido caem nesta classe quando o handler as mapeia.
Recurso — 404 NOT_FOUND
Pay-in intent not found. — intent inexistente ou de outro merchant (sem enumeração).
Disponibilidade PAY-IN — 409 PAY_IN_UNAVAILABLE
Pay-in is currently unavailable. — sem rota, rail, carteira ou conexão utilizável (merchant/readiness/routing). Não é um convite a forçar o par asset/rail.
Ritmo — 429 RATE_LIMITED
Too many requests. — definido de forma formal no Hosted Checkout (página/status/start e criação HTML). Login humano também pode devolver 429. A API PAY-IN de máquina não publica neste checkpoint um limite de ritmo próprio além da infra genérica.
Interno / temporário — 500
Código de envelope internal_error com mensagem genérica. Não são publicados stacks. Pode repetir GET; POST create só com a mesma idempotency key.
Hosted Checkout (pagador)
Token inválido: 404 genérico. 429 nos limites públicos. Estes códigos do pagador não substituem o envelope da API merchant.