Catálogo de erros

code	status	significado
unknown_parameter	400	chave desconhecida no corpo (param = a chave)
invalid_request	400	campo inválido/ausente (param quando aplicável)
missing_idempotency_key	400	Idempotency-Key ausente num POST de criação
invalid_idempotency_key	400	Idempotency-Key malformado
idempotency_key_reuse	409	mesma chave, body diferente
reserved_metadata_key	400	chave metadata com prefixo reservado
merchant_net_not_positive	400	link absorb com líquido ≤ 0
not_available_in_live	403	endpoint só-sandbox chamado em produção
invalid_api_key	401	chave inexistente/revogada
insufficient_scope	403	chave sem o escopo do endpoint
payment_link_not_found	404	link inexistente para o tenant
payment_not_found	404	pagamento inexistente para o tenant
event_not_found	404	evento inexistente (o endpoint de eventos é planejado)
internal_error	500	erro inesperado — cite request_id

---

Escopos

payment_links:write · payment_links:read (planejado) · payment_intents:read · payment_intents:write · quotes:read · quotes:write · payments:read · payments:write · events:read (planejado).

---

Contrato canônico v1. Divergência entre código e este documento é bug do código; alteração deste documento exige ADR.