Códigos de erro

Um único envelope para todas as falhas:

{ "error": { "code": "invalid_request", "message": "…" } }

HTTP	code	Quando	O que fazer
401	missing_api_key	Sem cabeçalho Authorization: Bearer sk_… nem X-API-Key	Acrescente a chave
401	invalid_api_key	Chave revogada, desconhecida ou conta inactiva	Verifique a chave e o estado da conta
403	insufficient_scope	A chave não tem esse direito (pagar, por exemplo)	Emita uma chave com o âmbito certo
403	client_inactive	A conta não está validada, ou está suspensa	Termine o processo KYB
403	not_live	Conta ainda não aberta ao modo real	Use uma chave sk_test_ entretanto
404	not_found	Recurso inexistente — ou não seu	Verifique o identificador
409	already_exists	Duplicado (referência já usada)	Releia o recurso existente
409	precondition_failed	O estado não permite a operação	Consulte o recurso, corrija o encadeamento
409	concurrent_request	Mesmo Idempotency-Key, corpo diferente	Não reutilize uma chave para duas operações
422	invalid_request	Corpo inválido (campo, montante, activo)	A message nomeia o campo em falta
422	insufficient_funds	Saldo insuficiente para este pagamento	Consulte GET /v1/balances
429	—	300 pedidos/minuto ultrapassados	Respeite o cabeçalho Retry-After
502	upstream_error	Uma dependência falhou	Reenvie com o mesmo Idempotency-Key
503	temporarily_unavailable	Indisponibilidade passageira	Reenvie com backoff

Reenviar sem risco

Os 502 e 503 reenviam-se sempre com o mesmo Idempotency-Key: se o primeiro pedido tinha chegado a bom porto do lado do servidor, recupera o seu resultado em vez de criar um duplicado.

Um 502 não quer dizer que nada aconteceu. Diz que uma dependência não respondeu, não que a operação não exista. É exactamente a situação para a qual existe a idempotência: reenvie, não volte a criar.

not_found sobre um recurso que existe

A API responde 404 também quando o recurso pertence a outro comerciante: nunca deduza a existência de um recurso a partir de um 404.

Um corpo recusado não é um campo ignorado

Um campo desconhecido num corpo JSON é ignorado em silêncio, não recusado. Um erro de escrita no nome de um campo opcional não produz portanto qualquer erro: produz uma operação criada sem aquilo que julgava ter enviado. Releia os nomes na referência em vez de confiar na ausência de um 422.