Erros

Todo erro da API pública tem o mesmo formato: um código estável para o seu código ler e uma mensagem para humanos.

Formato

Resposta 400

{
  "code": "INVALID_DOCUMENT",
  "message": "O CPF ou CNPJ informado é inválido.",
  "details": ["customer.document"]
}

Trate sempre pelo code. A message é texto de apresentação e pode mudar; details aparece quando há algo a listar, como os campos que falharam na validação.

Códigos de status

HTTP

`200` sucessoopcional	Leitura bem-sucedida.
`201` sucessoopcional	Recurso criado.
`204` sucessoopcional	Removido, sem corpo de resposta.
`400` erro do clienteopcional	Payload inválido ou regra de negócio recusada.
`401` erro do clienteopcional	Chave ausente, inválida, expirada ou revogada.
`403` erro do clienteopcional	A chave não tem o escopo necessário.
`404` erro do clienteopcional	O recurso não existe nesta conta.
`422` erro do clienteopcional	O adquirente recusou a operação.
`500` erro do servidoropcional	Falha inesperada. Pode ser repetida com a mesma chave de idempotência.

Códigos de erro

code

`UNAUTHORIZED` 401opcional	Chave ausente ou não aceita. A mensagem é propositalmente vaga: dizer o motivo ajudaria quem está testando chaves.
`INSUFFICIENT_SCOPE` 403opcional	Falta escopo. details traz os escopos exigidos.
`IDEMPOTENCY_KEY_REQUIRED` 400opcional	Faltou o header Idempotency-Key na criação.
`VALIDATION_ERROR` 400opcional	Campos inválidos no corpo. details lista o que falhou.
`INVALID_DOCUMENT` 422opcional	CPF ou CNPJ inválido.
`METHOD_NOT_SUPPORTED` 422opcional	O meio de pagamento pedido não está disponível na v1.
`METHOD_DISABLED` 422opcional	O meio de pagamento existe, mas foi desligado pelo administrador da plataforma.
`AMOUNT_BELOW_MINIMUM` 422opcional	Valor abaixo do mínimo configurado para a operação. A mensagem traz o mínimo em centavos e em reais.
`AMOUNT_ABOVE_MAXIMUM` 422opcional	Valor acima do máximo configurado para a operação. A mensagem traz o máximo em centavos e em reais.
`INSUFFICIENT_BALANCE` 422opcional	Saldo disponível menor que o valor mais a tarifa.
`CHARGE_NOT_FOUND` 404opcional	Cobrança inexistente ou de outra conta.
`PAYOUT_NOT_FOUND` 404opcional	Transferência inexistente ou de outra conta.
`WEBHOOK_NOT_FOUND` 404opcional	Webhook inexistente ou de outra conta.
`INVALID_WEBHOOK_URL` 422opcional	webhook_url (ou url do endpoint) não é http(s) ou aponta para localhost, IP privado ou link local.
`ACQUIRER_REJECTED` 422opcional	O adquirente recusou. A mensagem repassa o motivo quando existe, e charge_id aponta a cobrança gravada como failed.
`INTERNAL_ERROR` 500opcional	Falha inesperada do nosso lado.

Repetindo com segurança

Em 500 ou timeout, repita a chamada inteira com a mesma chave de idempotência. Em 4xx, repetir não ajuda: corrija o payload primeiro.

Formato#

Códigos de status#