Erros

Todo erro vem no mesmo envelope:

{
  "error": {
    "code": "card_declined",
    "message": "Pagamento não autorizado pelo emissor do cartão.",
    "retryable": false,
    "correlation_id": null,
    "payment_id": "<uuid>"
  }
}

code é estável: programe contra ele, nunca contra a message.
message é segura para log e nunca traz dado do comprador.
retryable: true quer dizer que repetir a mesma requisição, com a mesma Idempotency-Key, pode dar certo depois de alguns instantes.
correlation_id devolve o X-Correlation-Id que você enviou; payment_id vem quando o erro é de um pagamento já criado.

Códigos

Código	HTTP	Significado	O que fazer
`malformed_json`	400	o corpo não é JSON válido	corrija o corpo
`missing_idempotency_key`	400	falta o cabeçalho `Idempotency-Key`, ou ele está fora do formato	envie uma chave de 8 a 128 caracteres
`unauthorized`	401	chave ausente, inválida, revogada ou de outro ambiente	confira a chave e a base da API
`insufficient_scope`	403	a chave não tem a permissão da rota	peça uma chave com a permissão (Ambientes e chaves)
`merchant_disabled`	403	o estabelecimento está sem o produto de pagamentos online habilitado	fale com a CDX Pay
`not_found`	404	o pagamento não existe ou é de outro estabelecimento	confira o `id`
`idempotency_conflict`	409	a `Idempotency-Key` já foi usada com outro corpo	use uma chave nova para uma intenção nova
`idempotency_in_progress`	409	a requisição com essa chave ainda está em curso	espere e consulte o pagamento
`invalid_state`	409	a operação não cabe no status atual (por exemplo, capturar o que não está `pre_authorized`)	consulte o pagamento antes de agir
`merchant_not_provisioned`	409	o estabelecimento ainda não está pronto para cobrar	fale com a CDX Pay
`operation_unknown`	409	resultado ambíguo de uma operação, pendente de conciliação	não reenvie com outra chave; consulte o pagamento ou espere o webhook
`validation_error`	422	algum campo está ausente ou inválido	corrija e reenvie com nova `Idempotency-Key`
`invalid_card`	422	os dados do cartão são inválidos	peça ao comprador para conferir o cartão (novo `tokenize()`)
`card_expired`	422	o cartão está vencido	peça outro cartão (novo `tokenize()`, nova `Idempotency-Key`)
`card_declined`	422	o emissor recusou	mostre ao comprador; ele tenta outro cartão (novo `tokenize()`, nova `Idempotency-Key`)
`unsupported_operation`	422	a operação não é suportada (por exemplo, parcelamento inválido)	revise o pedido
`preauth_expired`	422	a pré-autorização venceu antes da captura	crie um pagamento novo
`amount_exceeds_refundable`	422	o estorno pedido é maior que o saldo estornável	consulte `captured_cents` e `refunded_cents`
`provider_rejected`	422	a rede de cartões recusou a captura ou o estorno; o pagamento continua no status anterior	consulte o pagamento e tente de novo mais tarde, com nova `Idempotency-Key`
`processing_error`	422	recusa técnica da rede de cartões, não do emissor	tente de novo em instantes, com novo `token_id` e nova `Idempotency-Key`
`customer_registration_failed`	422	os dados do comprador não foram aceitos; nada foi cobrado	confira documento, telefone e endereço e tente de novo com nova `Idempotency-Key`
`rate_limited`	429	limite de requisições por minuto excedido	espere alguns segundos e repita
`internal_error`	500	erro interno	se veio `payment_id`, consulte o pagamento antes de qualquer nova tentativa; se persistir, fale com o suporte informando o `correlation_id`
`provider_auth_error`	502	falha de comunicação da CDX Pay com a rede de cartões	tente mais tarde; se persistir, fale com o suporte
`provider_unavailable`	503	a rede de cartões está indisponível	repita com a mesma `Idempotency-Key` e o mesmo corpo depois de 30 s

Resultado ambíguo não é erro

Uma resposta HTTP 202 com o pagamento em unknown não é um erro: a operação foi enviada e o resultado ainda não é conhecido. Veja Autenticação e idempotência.