Erros

Todo erro — inclusive os que não previmos — tem a mesma forma:

{
  "error": {
    "type": "invalid_request_error",
    "code": "amount_below_minimum",
    "message": "O valor está abaixo do mínimo permitido.",
    "details": {}
  }
}

Baseie a sua lógica no code. Ele é contrato e não muda. A message é escrita para gente ler e pode ser reescrita a qualquer momento — inclusive para ficar melhor. Quando isso acontece, um if que compara a mensagem para de funcionar sem avisar.

As oito famílias

O type responde de quem é o problema e o que fazer. É por ele que você decide o comportamento; o code diz qual mensagem mostrar.

`type`	De quem é	O que fazer
`authentication_error`	Sua chave	Troque a chave. Não repita
`permission_error`	Seu escopo	Gere uma chave com o escopo certo. Não repita
`invalid_request_error`	Sua chamada	Corrija os dados. Repetir igual dá o mesmo erro
`idempotency_error`	Sua chave de idempotência	Chave nova, ou repita em instantes
`not_found_error`	O recurso	Confira o código. Não repita
`rate_limit_error`	Ritmo	Espere o `Retry-After` e repita
`card_error`	O cartão do comprador	Mostre a `message` e ofereça outro meio. Não repita
`api_error`	Nosso	Repita com a mesma `Idempotency-Key`. Não reescreva a chamada

A divisão que importa na prática: invalid_request_error se corrige mudando a chamada, authentication_error trocando a chave, e api_error é nosso — repita, não reescreva. card_error é o único que descreve uma cobrança que existe. Os outros sete recusam a chamada antes de criar qualquer coisa; um 402 card_declined devolve em details.charge_id o ch_ de uma cobrança já gravada com status failed. Tratá-lo como os demais e descartar a resposta deixa você sem a tentativa que o comprador jura ter feito. Ver Cobrança no cartão.

`details`

details é sempre objeto, mesmo vazio. Em validation_failed, ele traz os campos recusados e as mensagens de cada um:

{
  "error": {
    "type": "invalid_request_error",
    "code": "validation_failed",
    "message": "Alguns campos não passaram na validação.",
    "details": {
      "amount": ["O valor deve ser um inteiro em centavos (R$ 10,00 = 1000)."],
      "customer.name": ["O campo nome é obrigatório."]
    }
  }
}

Em insufficient_scope, ele traz required_ability e a lista de abilities que a chave tem.

Catálogo de códigos

Todos são estáveis. Se um código novo aparecer, ele entra nesta tabela — nenhum destes muda de significado.

`code`	HTTP	`type`	O que fazer
`missing_api_key`	401	`authentication_error`	Envie `Authorization: Bearer sk_…`
`invalid_api_key`	401	`authentication_error`	Confira se copiou a chave inteira e o ambiente certo
`revoked_api_key`	401	`authentication_error`	A chave existiu e foi desligada. Gere outra em Desenvolvedores
`expired_api_key`	401	`authentication_error`	Gere outra em Desenvolvedores
`insufficient_scope`	403	`permission_error`	A chave é válida, falta o escopo. `details.required_ability` diz qual
`one_click_requires_three_ds`	403	`permission_error`	Você pediu `three_d_secure: "required"` num cartão guardado, que não pode autenticar
`resource_not_found`	404	`not_found_error`	O recurso não existe — ou é de outra conta
`card_not_found`	404	`not_found_error`	O `pm_` não existe, ou é de outro comprador
`card_declined`	402	`card_error`	A operadora recusou. A cobrança existe, em `details.charge_id`, com status `failed`
`card_not_available`	422	`invalid_request_error`	Em `POST /v1/cards`: esta conta não vende no cartão. `details.reason` diz por quê
`three_ds_unavailable`	422	`invalid_request_error`	Em `POST /v1/three_ds_tokens`: esta conta não consegue autenticar o portador
`pix_failed`	402	`api_error`	Não conseguimos gerar o código Pix. Ofereça o cartão, ou tente de novo
`idempotency_key_too_long`	400	`invalid_request_error`	Encurte a chave para 255 caracteres
`idempotency_key_reused`	409	`idempotency_error`	A chave já foi usada com outro corpo. Use uma chave nova
`idempotency_key_in_progress`	409	`idempotency_error`	A primeira ainda está em voo. Repita em instantes
`validation_failed`	422	`invalid_request_error`	`details` traz campo → mensagens. Corrija e reenvie
`amount_below_minimum`	422	`invalid_request_error`	Valor abaixo do mínimo permitido
`amount_above_maximum`	422	`invalid_request_error`	Valor acima do máximo permitido
`items_do_not_match_amount`	422	`invalid_request_error`	A soma de `quantity * amount` dos itens tem que bater com `amount`
`seller_not_approved`	422	`invalid_request_error`	Nada na chamada resolve. O caminho é o painel
`provider_rejected`	422	`invalid_request_error`	Confira os dados do comprador e o valor
`card_expired`	422	`invalid_request_error`	O cartão guardado venceu. Peça um novo ao comprador
`card_revoked`	422	`invalid_request_error`	O cartão guardado foi removido. Peça um novo ao comprador
`card_not_usable_on_account`	422	`invalid_request_error`	O cartão não vale na conta que está cobrando. Ver Cofre de cartões
`charge_not_refundable`	422	`invalid_request_error`	Só cobrança paga é estornável
`exceeds_remaining`	422	`invalid_request_error`	Peça no máximo o saldo estornável, ou omita `amount`
`refund_window_closed`	422	`invalid_request_error`	Passaram-se 90 dias desde o pagamento. Não há retentativa
`refund_disabled`	422	`invalid_request_error`	Estorno não habilitado para a conta. Fale com o suporte
`insufficient_balance`	422	`invalid_request_error`	Em `POST /v1/withdrawals`: peça no máximo o `withdrawable` do saldo
`negative_balance`	422	`invalid_request_error`	Em `POST /v1/withdrawals`: a conta tem dívida de estorno. As próximas vendas cobrem
`amount_below_fee`	422	`invalid_request_error`	Em `POST /v1/withdrawals`: o valor precisa ser maior que a taxa de saque
`no_pix_key`	422	`invalid_request_error`	Em `POST /v1/withdrawals`: mande `pix_key_type` e `pix_key`, ou cadastre uma chave padrão
`no_bank_account`	422	`invalid_request_error`	Em `POST /v1/withdrawals`, no split: cadastre a conta bancária padrão no painel
`no_pooled_account`	422	`invalid_request_error`	Em `POST /v1/withdrawals`: nada na chamada resolve. Fale com o suporte
`too_many_requests`	429	`rate_limit_error`	Espere o `Retry-After` e repita
`provider_rate_limited`	429	`rate_limit_error`	Limite do provedor. Repita com backoff
`internal_error`	500	`api_error`	Repita com a mesma `Idempotency-Key`
`provider_unavailable`	502	`api_error`	Repita com a mesma `Idempotency-Key` — a cobrança pode ter sido criada
`platform_unavailable`	503	`api_error`	É problema nosso. Repita depois; nada na chamada resolve

Tratando na prática

$erro = $resposta->json('error');

match ($erro['type']) {
    'api_error', 'rate_limit_error' => $this->repetir($chaveIdempotencia),
    'authentication_error', 'permission_error' => $this->alertarOperacao($erro['code']),
    default => $this->registrarFalhaDoPedido($erro['code'], $erro['details']),
};

const { error } = await resposta.json();

switch (error.type) {
  case 'api_error':
  case 'rate_limit_error':
    return repetir(chaveIdempotencia);
  case 'authentication_error':
  case 'permission_error':
    return alertarOperacao(error.code);
  default:
    return registrarFalhaDoPedido(error.code, error.details);
}

erro = resposta.json()["error"]

if erro["type"] in ("api_error", "rate_limit_error"):
    repetir(chave_idempotencia)
elif erro["type"] in ("authentication_error", "permission_error"):
    alertar_operacao(erro["code"])
else:
    registrar_falha_do_pedido(erro["code"], erro["details"])

Registre code, type e o horário da chamada no seu log. São esses três que permitem localizar a requisição do nosso lado quando você abre um chamado.

Veja também

Repetir com segurança

A matriz de qual código merece retry.

Limites de requisição

Como não chegar no 429.

Ficou algo de fora? Chame no WhatsApp. Se o assunto for uma chamada específica, informe o horário dela; se for uma entrega de webhook, informe o X-Vext-Delivery — é por ele que localizamos a tentativa, a resposta do seu servidor e o horário.

Começar

Pix

Cartão

Boleto

Convenções da API

Depois da venda

Webhooks

Receitas

As oito famílias

`details`

Catálogo de códigos

Tratando na prática

Veja também

Repetir com segurança

Limites de requisição

​As oito famílias

​details

​Catálogo de códigos

​Tratando na prática

​Veja também

Repetir com segurança

Limites de requisição

As oito famílias

`details`

Catálogo de códigos

Tratando na prática

Veja também