Erros

A API usa códigos HTTP para indicar o resultado de cada requisição. Um erro da própria API responde um envelope de dois campos:

{
  "status": "error",
  "error": "insufficient_scope"
}

Use error para tratar o caso no seu código. É um identificador estável, não uma frase: a API não devolve uma descrição junto.

Tipos de erro

HTTP	error	Quando acontece
401	`unauthenticated`	Chave ausente, malformada, inválida ou revogada
403	`insufficient_scope`	A chave não tem o escopo que a rota exige
404	`not_found`	O recurso não existe ou pertence a outra conta
409	`idempotency_in_progress`	Já há uma requisição com essa `Idempotency-Key` em andamento
409	`idempotency_key_reuse`	A `Idempotency-Key` voltou com outro corpo
422	`idempotency_key_required`	Requisição que altera dados, enviada sem o header `Idempotency-Key`

404 e “não é sua” são a mesma resposta. Um id que existe mas pertence a outra conta responde not_found, sem dizer que existe.

Validação

Quando os dados enviados são inválidos, a resposta é 422 em outro formato: o do validador, com os campos que precisam ser corrigidos.

{
  "message": "The name field is required.",
  "errors": {
    "name": ["The name field is required."]
  }
}

São duas formas diferentes de 422, então discrimine pela presença de errors. Um campo que a API não aceita cai aqui: enviar secondary_color em um checkout, por exemplo, derruba a requisição inteira em vez de ser ignorado. Veja O que mudou.

Limite excedido

429 quando a chave passou do limite por minuto, com Retry-After dizendo quanto esperar. Veja Rate limits.

Em erros 5xx, uma operação pode não ter sido concluída. Se a requisição altera dados, repita a chamada com a mesma Idempotency-Key: um 5xx não fica guardado, então o reenvio executa a operação de verdade.

Introdução

Quickstart

Guias

Receitas

Produtos

Pedidos

Reembolsos

Chargebacks

Checkouts

Upsells

Métricas

Vendas

Assinaturas

Webhooks

Outros

Chargebacks

Checkouts

Métricas

Pedidos

Ping

Produtos

Reembolsos

Vendas

Assinaturas

Upsells

Webhooks

Tipos de erro

Validação

Limite excedido

​Tipos de erro

​Validação

​Limite excedido

Tipos de erro

Validação

Limite excedido