Erros e novas tentativas
Erros da API usam um formato consistente. O código é para lógica do aplicativo; a mensagem explica o problema. Mantenha a entrada do usuário intacta e ofereça um próximo passo claro.
Nesta página
Um formato de erro#
Respostas não incluem rastreamentos de pilha, SQL, tokens nem uma resposta completa do provedor externo. Não exiba logs internos brutos a um cliente.
{
"error": {
"code": "GATEWAY_NOT_CONNECTED",
"message": "Financial operations are temporarily unavailable. Try later or contact support."
}
}Grupos de erro comuns#
| HTTP | Exemplos | Próximo passo |
|---|---|---|
| 400 | INVALID_JSON, UNKNOWN_FIELD, INVALID_INPUT | Verifique a entrada e os campos permitidos |
| 401 | AUTH_REQUIRED, SESSION_EXPIRED | Faça login novamente |
| 403 | INVALID_ORIGIN, CSRF_REQUIRED | Verifique a origin e a sessão atual |
| 404 | NOT_FOUND, TICKET_NOT_FOUND | Verifique o endereço e a propriedade |
| 409 | CHALLENGE_UNAVAILABLE | Inicie um novo login |
| 410 | CHALLENGE_EXPIRED | Crie um novo link de login |
| 413 | REQUEST_TOO_LARGE | Reduza o corpo da solicitação |
| 415 | JSON_REQUIRED | Envie application/json |
| 429 | RATE_LIMITED | Reduza a frequência e aguarde |
| 503 | GATEWAY_NOT_CONNECTED, SERVICE_UNAVAILABLE | Verifique a disponibilidade ou tente mais tarde |
Limites de taxa#
| Ação | Limite |
|---|---|
| Iniciar login | 6 por minuto por endereço com hash |
| Verificar um desafio | 90 por minuto por desafio |
| Pergunta de conhecimento | 12 por minuto por endereço com hash com D1 |
| Criar um link de servidor | 20 por minuto por usuário |
| API de comerciante | 90 solicitações por minuto por chave |
| Novo aplicativo | Cinco por dia por usuário |
| Retomar aplicativo / decisão do moderador | 30 por minuto por usuário para cada ação |
| Revisão de site com IA | 30 por hora em todo o serviço |
| Leia o checkout ou tente efetuar um pagamento | 90 por minuto por endereço com hash |
| Crie uma solicitação de suporte | 6 por hora por usuário |
| Teste uma notificação | 3 por hora por usuário |
| Geração com IA | 60 por hora em todo o serviço por padrão |
O que pode ser repetido#
Uma leitura pode ser repetida após um atraso em uma falha temporária de rede. Antes de repetir uma mutação, verifique se a operação original foi concluída; uma resposta perdida não prova uma falha.
Operações financeiras exigem idempotência e uma verificação do status do servidor. Um redirecionamento do cliente para uma página de resultado não substitui uma confirmação.
O que incluir em uma solicitação#
- A página e a ação imediatamente anteriores ao erro.
- Hora, fuso horário e o código de erro visível.
- Sua fatura ou referência de solicitação de suporte, se disponível.
- Uma breve descrição do resultado que você esperava.