Todo erro retornado pela Studio API segue uma estrutura JSON consistente, facilitando a construcao de um tratamento de erros confiavel na sua aplicacao.
Formato de Resposta de Erro
Todos os erros seguem uma estrutura JSON consistente:
{
"statusCode": 400,
"message": "Bad Request Error",
"errors": [
{
"message": "required",
"path": "email"
}
]
}
O array errors fornece detalhes de validacao em nivel de campo quando disponivel. Pode estar ausente para erros que nao sao de validacao (ex.: 401, 500).
Codigos de Status HTTP Comuns
| Status | Codigo | Descricao |
|---|
400 | validation_error | Entrada invalida ou falha de validacao |
401 | unauthorized | Autenticacao 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 requerendo acao do usuario:
| Codigo | Descricao | Acao Necessaria |
|---|
auth.organization_selection_required | Usuario pertence a multiplas organizacoes | Chame Trocar Organizacao |
auth.otp_verification_required | Verificacao de email pendente | Complete a verificacao OTP |
auth.method_not_allowed | Usuario registrado via um metodo de autenticacao diferente | Use o fluxo de autenticacao correto (ex.: OAuth ao inves de senha) |
Nao trate todas as respostas 403 da mesma forma. Algumas requerem acoes especificas do usuario (selecao de organizacao, verificacao OTP) ao inves de simples negacao de permissao. Sempre inspecione o campo message para determinar o caminho de recuperacao correto.
Exemplo de Tratamento de Erro
curl -s -w "\n%{http_code}" https://api.awsales.io/studio/profile \
-H "Authorization: Bearer INVALID_TOKEN"
# Response body:
# {"statusCode":401,"message":"Unauthorized"}
# HTTP status: 401
Para erros de rate limit 429 e erros de servidor 5xx, implemente exponential backoff com um atraso base de 1 segundo e maximo de 3 tentativas. Sempre inclua um componente de jitter para evitar efeitos de thundering herd.
