(11) Referência

Erros

A forma de um erro, os códigos HTTP e os códigos estáveis da API.

A forma de um erro

Um erro da API tem sempre o mesmo corpo: um código estável em erro, para o teu programa decidir, e uma explicação em português em mensagem, para mostrar a uma pessoa (ou para o registo). No 422 dados_invalidos vem ainda campos, com uma mensagem por campo.

422 Unprocessable Entity

{
  "erro": "dados_invalidos",
  "mensagem": "Há campos por corrigir.",
  "campos": {
    "amount": "Em AOA o valor é em kwanzas inteiros (múltiplo de 100 unidades menores): os gateways angolanos não cobram cêntimos."
  }
}

Decide pelo erro, e nunca pelo texto da mensagem, que pode ser reescrito. Os códigos não mudam de significado; quando aparecer um novo, trata-o como o código HTTP diz.

Os códigos HTTP

HTTP	Quer dizer	Repetir?
2xx	Feito. 201 quando criou alguma coisa.	Não é preciso
400	O pedido está mal formado.	Só depois de o corrigir
401	A chave falta ou não serve.	Não, até trocar a chave
404	O recurso não existe para esta chave e este modo. Uma rota que não existe responde 404 em texto simples, sem JSON.	Não
409	O estado do recurso não deixa fazer isto.	Não
422	Os dados estão bem formados mas não servem.	Só depois de os corrigir
500, 503	Falha do nosso lado.	Sim, com a mesma Idempotency-Key

Os códigos estáveis

HTTP	erro	Quando
400	`pedido_invalido`	O corpo não é JSON, passa de 64 KB, ou traz um campo que não existe.
400	`idempotencia_em_falta`	Um POST sem o cabeçalho Idempotency-Key.
400	`idempotencia_invalida`	O Idempotency-Key passa de 255 carateres.
401	`sem_chave`	Sem Authorization: Bearer, ou com um valor que não começa por sk_test_ nem sk_live_.
401	`chave_invalida`	A chave não existe, foi revogada, ou deixou de servir depois de uma rotação.
404	`sessao_nao_existe`	Não há sessão com esse id para esta chave (o modo conta).
404	`pagamento_nao_existe`	Não há pagamento com esse id para esta chave.
404	`estorno_nao_existe`	Não há estorno com esse id para esta chave.
404	`subscricao_nao_existe`	Não há subscrição com esse id para esta chave.
409	`pagamento_nao_pago`	Pediste um estorno de um pagamento que não está confirmado.
409	`pagamento_ja_estornado`	O pagamento já foi todo estornado.
409	`subscricao_terminada`	A subscrição já terminou: não há nada a cancelar, nem página do cliente a abrir.
422	`dados_invalidos`	Há campos por corrigir: o objeto campos tem uma mensagem por campo.
422	`idempotencia_reutilizada`	A mesma Idempotency-Key com outro corpo, ou noutra rota.
422	`moeda_sem_gateway`	Não há gateway para cobrar nesta moeda, por estes métodos, neste modo.
422	`metodo_sem_gateway`	Pediste em payment_methods um método que não tem gateway neste modo e nesta moeda.
422	`estorno_acima_do_cobrado`	O estorno passa o que resta do pagamento. A mensagem diz quanto resta.
500	`erro_interno`	Uma falha nossa. Nada ficou feito a meio; repete com a mesma Idempotency-Key.
503	`indisponivel`	Não foi possível validar a chave agora. Repete daqui a pouco.

Nos SDK

Uma recusa da API chega como um erro com o estado HTTP, o código e a mensagem: *spolly.Error em Go (lê-se com errors.As, e o código está em Code) e SpollyError em JavaScript (status, code, userMessage, fields; compara com ErrorCodes). Os SDK repetem sozinhos os 429, 500, 502, 503, 504 e as falhas de rede, com a mesma Idempotency-Key; um 4xx nunca se repete.