Erros

Toda resposta de erro tem a mesma forma, em qualquer endpoint e em qualquer código HTTP:

{
  "error": {
    "code": "external_id_conflict",
    "message": "Já existe uma cobrança com este externalId e dados diferentes.",
    "requestId": "8762ae31-b2c8-4032-800b-6d7f6a45331e"
  }
}

Escreva seu if em cima de code: ele não muda. A message é para humano ler e pode melhorar com o tempo. Guarde o requestId no seu log — é por ele que o suporte acha a requisição.

Em erro de validação vem também details, com um item por campo recusado.

Código	HTTP	Significa
`invalid_request`	400	O corpo ou os parâmetros da requisição são inválidos.
`invalid_api_key`	—	Chave de API ausente, malformada ou inexistente.
`revoked_api_key`	—	Esta chave de API foi revogada.
`merchant_not_activated`	403	A conta ainda não está liberada para cobrar. Conclua a ativação no painel.
`charge_blocked`	403	Esta conta está impedida de gerar cobranças.
`missing_merchant_id`	403	A conta ainda não tem identificador no provedor. Faça uma compra pelo painel primeiro.
`charge_not_found`	404	Cobrança não encontrada nesta conta.
`external_id_conflict`	409	Já existe uma cobrança com este externalId e dados diferentes.
`charge_processing`	409	Uma cobrança com este externalId está sendo criada agora. Tente de novo em instantes.
`charge_not_cancelable`	409	Só é possível cancelar uma cobrança que ainda não foi paga.
`invalid_transition`	409	A cobrança não pode ir para esse estado a partir do estado atual.
`idempotency_key_conflict`	409	Esta Idempotency-Key já foi usada com um corpo diferente.
`rate_limited`	429	Muitas requisições. Veja o cabeçalho Retry-After.
`provider_error`	402	O provedor de Pix recusou a cobrança.
`provider_unavailable`	—	O provedor de Pix está indisponível. Tente de novo.
`not_available_in_live`	403	Esta rota só existe no ambiente de testes (chave p2d_test_).
`internal_error`	—	Erro interno. Se persistir, fale com o suporte.

O que repetir e o que não

rate_limited (429) — espere o que diz o cabeçalho Retry-After e repita.
charge_processing (409) — a mesma cobrança está sendo criada agora, por outra requisição sua. Repita em 1 segundo.
provider_unavailable (503) e erros 5xx — repita com espera crescente.
provider_error (402) — o provedor recusou. Repetir igual dá igual.
external_id_conflict (409) — você mandou o mesmo externalId com outro valor. Confira qual dos dois pedidos está certo.
4xx em geral — corrija a requisição antes de repetir.