A resposta curta: todos os erros têm a mesma forma, com um code estável, em inglês, que é o que o seu programa deve comparar. Vale a pena repetir, com espera, só os 429, 500, 502 e 503. Os outros não se resolvem a repetir: é preciso mudar alguma coisa.
A forma de um erro
{
"error": {
"code": "rate_limited",
"message": "Demasiados pedidos. Tente de novo daqui a pouco.",
"correlation_id": "0f8fad5b-d9cb-469f-a165-70867728950e",
"details": { "retry_after": 42 }
}
}
| Campo |
O que é |
| code |
Código estável, em inglês. Use este campo nos seus programas: nunca muda com a língua. |
| message |
Texto para pessoas, na língua de Accept-Language (pt ou en; sem o cabeçalho, inglês). Pode mudar: não o use em comparações. |
| correlation_id |
O identificador do pedido, igual ao cabeçalho X-Correlation-ID. |
| details |
Dados extra sobre o erro, como o campo inválido ou a razão de um 409. Pode vir vazio. |
Os códigos, um a um
| Estado e código |
O que quer dizer |
O que fazer |
| 400 invalid_request |
O pedido não é válido: o corpo não é JSON, a ligação não é HTTPS, ou o modo pedido em X-API-Mode não é o da chave. |
Corrija o pedido. |
| 401 unauthorized |
Chave em falta, inválida, revogada ou fora da validade, ou quem a criou já não tem acesso à conta. |
Confirme a chave ou crie outra. |
| 402 insufficient_credit |
A conta não tem saldo suficiente. Nada foi cobrado. |
Carregue o saldo e repita. |
| 403 forbidden |
A conta não pode usar a API neste momento. |
Contacte o suporte. |
| 403 insufficient_scope |
A chave não tem a permissão necessária. |
Crie uma chave com essa permissão. |
| 403 ip_not_allowed |
O IP de origem não está na lista da chave. |
Use um IP da lista ou crie outra chave. |
| 403 spending_limit_exceeded |
A operação passa o limite de gastos da chave. Nada foi cobrado. |
Crie uma chave com um limite maior. |
| 404 not_found |
O recurso não existe ou não é da sua conta. |
Confirme o endereço e o identificador. |
| 405 method_not_allowed |
O método não é aceite neste caminho. |
Veja o cabeçalho Allow. |
| 409 conflict |
Não se pode fazer no estado actual. A razão vem em details.reason. |
Veja a razão e corrija. |
| 409 account_email_domain |
O pedido mexe no correio do domínio do e-mail da conta, ou de um utilizador dela. |
Faça a alteração no Meu MozOut. |
| 409 idempotency_conflict |
A Idempotency-Key foi usada noutro pedido, ou o primeiro ainda está em curso. |
Veja as repetições. |
| 422 validation_failed |
Alguns dados não são válidos. |
Corrija-os, com a ajuda de details. |
| 429 rate_limited |
Passou o limite de pedidos. |
Espere o tempo de Retry-After. |
| 500 internal_error |
Falha do nosso lado. |
Tente mais tarde e indique o correlation_id ao suporte. |
| 502 upstream_error |
O serviço por trás da API não respondeu como esperado. |
Tente mais tarde e indique o correlation_id ao suporte. |
| 503 disabled |
A API está desligada neste momento. |
Tente mais tarde. |
Há ainda um código próprio do SMS, 403 sms_reseller_required, quando a conta não tem a revenda de SMS activa. Cada área tem também razões próprias dentro de 409 e 422, como cname_conflict no DNS ou action_in_progress nos servidores: estão nos artigos de cada área.
Repetir ou não repetir
| 1 |
Repetir, com espera: 429, 500, 502 e 503. No 429, espere pelo menos o Retry-After; se repetir, aumente a espera a cada tentativa.
|
|
| 2 |
Não repetir sem mudar nada: todos os outros. Um 422 volta a dar 422 enquanto os dados estiverem errados.
|
|
| 3 |
Num POST, envie sempre Idempotency-Key logo na primeira tentativa e repita com o mesmo valor. Assim, repetir depois de um 500 nunca faz a mesma coisa duas vezes: veja a Idempotency-Key.
|
|
|
Um 502 na hospedagem pode querer dizer que a alteração ficou feita. Se o pedido já tinha seguido para o servidor, repetir com a mesma Idempotency-Key devolve o mesmo 502 sem voltar a executar. Confirme primeiro o resultado com uma leitura e, para tentar de novo, use outra chave de idempotência.
|
Comunicar um problema ao suporte
Indique o correlation_id (ou o cabeçalho X-Correlation-ID), a hora do pedido e a operação. Nunca envie a chave: o suporte não precisa dela para encontrar o pedido.
|
Para o seu código: decida pelo estado HTTP (repetir ou não) e pelo code (o que mostrar ou fazer), e registe sempre o correlation_id. Nunca compare o message: muda com a língua e pode mudar de redacção.
|
|
Tem um erro que não percebe? Abra um pedido de suporte com o correlation_id, a hora e a operação, mas nunca com a chave.
Abrir um pedido de suporte
|
PRODUTO RECOMENDADO Hospedagem de sites com cPanel Domínio e SSL incluídos, cópias diárias e o painel que já conhece. desde 396,00 MT/mês (plano de 3 anos, com cupão) Ver planos |
Português
English
