Todos os erros da API Admin seguem uma estrutura JSON consistente, tornando simples o tratamento de erros de forma programatica em todos os endpoints.
Formato de Resposta de Erro
Todos os erros seguem uma estrutura JSON consistente:
{
"statusCode": 400,
"message": "Bad Request Error",
"errors": [
{
"message": "required",
"path": "email"
}
]
}
errors fornece detalhes de validacao a nivel de campo quando disponivel. Para erros que nao sao de validacao, apenas statusCode e message estao presentes.
Codigos de Status HTTP Comuns
| Status | Codigo | Descricao |
|---|
400 | validation_error | Entrada invalida ou falha de validacao |
401 | unauthorized | Sessao ausente ou invalida |
403 | forbidden | Permissoes insuficientes ou acao adicional necessaria |
404 | {entity}.not_found | Recurso nao existe |
409 | {entity}.{conflict} | Recurso duplicado ou conflito de estado |
422 | {entity}.{rule} | Violacao de regra de negocio |
500 | internal_server_error | Ocorreu um erro inesperado |
Sub-Codigos 403
A resposta 403 pode incluir contexto adicional que requer acao do usuario:
| Codigo | Descricao | Acao Necessaria |
|---|
auth.organization_selection_required | Usuario pertence a multiplas organizacoes | Selecione uma organizacao |
auth.otp_verification_required | Verificacao de email pendente | Complete a verificacao OTP |
auth.method_not_allowed | Metodo de autenticacao nao permitido pela organizacao | Use o fluxo de autenticacao correto |
Uma resposta 403 nem sempre significa “permissoes insuficientes.” Verifique o codigo de erro — pode indicar que verificacao OTP ou selecao de organizacao e necessaria antes de prosseguir.
Exemplos de Tratamento de Erros
curl -s -w "\n%{http_code}" https://api.awsales.io/admin/users \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" | {
body=$(head -1)
status=$(tail -1)
if [ "$status" -ne 200 ]; then
echo "Error $status: $body"
fi
}
Estrategia de retry: Para erros 500, implemente backoff exponencial com no maximo 3 tentativas. Para erros 429 (rate limit), respeite o header Retry-After. Nunca faca retry de erros 400, 401, 403 ou 404 — estes requerem acao corretiva.
