Todos os erros da API devolvem um corpo JSON com um campo error. Uma resposta 4xx geralmente exige corrigir o pedido, a conta ou o limite; uma resposta 5xx é do servidor ou temporária, mas a segurança de uma nova tentativa continua a depender da ação.
| Código | Nome | Significado |
|---|---|---|
| 400 | Bad Request | A validação falhou porque falta um valor obrigatório, está malformado, não é suportado ou está fora do intervalo permitido. Corrija o pedido antes de repetir. |
| 403 | Forbidden | A chave ou conta não tem permissão para executar esta ação, por exemplo quando a conta está suspensa. Repetir sem alterações não ajudará. |
| 404 | Not Found | O recurso da API solicitado não foi encontrado ou não está disponível para esta chave. Confirme o identificador e a propriedade da conta antes de repetir. |
| 409 | Conflict | O pedido entra em conflito com o estado existente, por exemplo ao reutilizar um request_id de add para outro pedido lógico. Use o pedido original ou um novo identificador único, conforme apropriado. |
| 413 | Content Too Large | O corpo do pedido é demasiado grande. Reduza a carga ou divida os pedidos em lote suportados antes de repetir. |
| 429 | Too Many Requests | Um limite de taxa ou ação rejeitou o pedido. Consulte X-RateLimit-DeniedBy quando existir e aguarde o número relativo de segundos indicado por X-RateLimit-Reset. |
| 500 | Internal Server Error | Ocorreu uma falha inesperada do servidor. Não presuma que é seguro repetir qualquer escrita; siga as orientações de repetição e reconciliação específicas da ação. |
| 502 | Bad Gateway | O provedor rejeitou a solicitação de execução. Confira a disponibilidade do serviço e os dados da solicitação antes de tentar novamente. |
| 503 | Service Unavailable | A API ou uma operação necessária está temporariamente indisponível, inclusive quando nenhum provedor elegível está disponível (provider_not_found). Repita mais tarde com atraso progressivo, respeite Retry-After quando presente e preserve o mesmo identificador de idempotência quando a ação o suportar. |
{
"error": "Missing required parameter: service"
}A ação exige um parâmetro que não foi incluído. Adicione-o ao corpo da requisição e tente novamente.
{
"error": "Invalid API key"
}Chave errada, chave revogada ou chave ausente. Verifique se o valor corresponde ao que é mostrado em /dashboard/api. O erro é idêntico para chave ausente e inválida para evitar ataques de enumeração.
{
"error": "Insufficient balance"
}O saldo da sua conta está abaixo da cobrança total do pedido. Adicione fundos via /dashboard/wallet ou aplique um cupom.
{
"error": "Service not found"
}O ID do serviço não existe. Atualize o catálogo com action=services e escolha um ID atual; serviços descontinuados usam outro erro 400.
{
"error": "Rate limit exceeded"
}Um limite de taxa ou ação rejeitou o pedido. Consulte X-RateLimit-DeniedBy quando existir e aguarde o número relativo de segundos de X-RateLimit-Reset.
{
"error": "language must be one of en, es, pt, ru, tr, ar, hi, id, fr, zh",
"error_code": "INVALID_LANGUAGE"
}services e catalog aceitam apenas en, es, pt, ru, tr, ar, hi, id, fr ou zh. Corrija o idioma antes de tentar novamente.
Repita action=add com o mesmo request_id e a mesma solicitação lógica para evitar duplicidade; use um novo valor exclusivo para outro pedido. Ações de leitura podem ser repetidas com segurança. Tentativas de cancelamento são seguras enquanto o pedido continuar elegível.