Erros e códigos de estado
Os erros são JSON, sempre com a mesma forma, e trazem sempre um código estável legível por máquina. Ramifique pelo código, não pela mensagem.
A forma
Qualquer falha devolve um objeto com um error legível por uma pessoa e um code estável. A mensagem é escrita para uma pessoa e pode ser reformulada; o código é um compromisso e não muda nas suas costas.
{
"error": "That file is larger than the 200 MB limit on your plan.",
"code": "VALIDATION_FAILED"
}Códigos que deve tratar
| Código | HTTP | O que significa |
|---|---|---|
| NOT_AUTHENTICATED | 401 | Token bearer em falta ou mal formado |
| FORBIDDEN | 403 | A chave é válida mas não tem permissão para isto |
| NOT_ENTITLED | 402 | O plano da conta não inclui acesso à API |
| VALIDATION_FAILED | 400 / 413 | Pedido incorreto, conversão não suportada ou ficheiro demasiado grande |
| NOT_FOUND | 404 | Não existe tal trabalho, ou pertence a outra conta |
| RATE_LIMITED | 429 | Limite horário atingido. Espere e tente de novo. |
| INTERNAL | 500 | Algo se partiu do nosso lado. É seguro repetir. |
O que vale a pena repetir
429 e 500 valem a pena repetir, com um atraso — afastando as tentativas em vez de entrar em ciclo, porque as repetições contam para o seu limite horário como qualquer outro pedido.
Tudo o resto é permanente para aquele pedido. Repetir um 400, um 402 ou um 404 produz a mesma resposta e gasta o seu limite a descobri-lo.
Um 502 ou 503 sem corpo JSON não veio da aplicação — é o proxy à frente dela, e aí vale sempre a pena repetir.