Tratamento de Erros A API My ID Virtual utiliza códigos de status HTTP padrão e retorna respostas estruturadas para ajudar você a identificar e tratar erros de forma eficiente.
Códigos de Status HTTP 2xx - Sucesso Código Status Descrição 200OK Requisição processada com sucesso 201Created Recurso criado com sucesso 204No Content Requisição processada, sem conteúdo de retorno
4xx - Erros do Cliente Código Status Descrição 400Bad Request Dados da requisição inválidos 401Unauthorized Token de autenticação ausente ou inválido 403Forbidden Permissões insuficientes para acessar o recurso 404Not Found Recurso não encontrado 409Conflict Conflito com o estado atual do recurso 422Unprocessable Entity Dados válidos mas não processáveis 429Too Many Requests Limite de taxa excedido
5xx - Erros do Servidor Código Status Descrição 500Internal Server Error Erro interno do servidor 502Bad Gateway Erro de gateway 503Service Unavailable Serviço temporariamente indisponível
Estrutura de Resposta de Erro Todas as respostas de erro seguem um formato consistente:
{ "statusCode" : 400 , "message" : "Descrição do erro" , "error" : "Bad Request" , "timestamp" : "2024-01-15T10:30:00.000Z" , "path" : "/api/endpoint" }
Exemplo de Erro de Validação { "statusCode" : 422 , "message" : [ "email deve ser um email válido" , "password deve ter pelo menos 6 caracteres" ], "error" : "Unprocessable Entity" , "timestamp" : "2024-01-15T10:30:00.000Z" , "path" : "/auth/signup" }
Erros Comuns por Módulo Autenticação
{ "statusCode" : 401 , "message" : "Token inválido ou expirado" , "error" : "Unauthorized" }
Solução : Faça login novamente ou use o refresh token
422 - Credenciais Inválidas
{ "statusCode" : 422 , "message" : "Email ou senha incorretos" , "error" : "Unprocessable Entity" }
Solução : Verifique as credenciais fornecidas
{ "statusCode" : 403 , "message" : "Código OTP é obrigatório" , "error" : "Forbidden" }
Solução : Forneça o código OTP válidoUsuários
404 - Usuário Não Encontrado
{ "statusCode" : 404 , "message" : "Usuário não encontrado" , "error" : "Not Found" }
Solução : Verifique se o ID do usuário está correto
409 - Email Já Cadastrado
{ "statusCode" : 409 , "message" : "Email já está em uso" , "error" : "Conflict" }
Solução : Use um email diferente
403 - Permissão Insuficiente
{ "statusCode" : 403 , "message" : "Sem permissão para acessar este usuário" , "error" : "Forbidden" }
Solução : Verifique se possui permissão para acessar o recursoServidores VPN
422 - Configuração Inválida
{ "statusCode" : 422 , "message" : "Configuração do servidor inválida" , "error" : "Unprocessable Entity" }
Solução : Verifique os parâmetros de configuração
404 - Servidor Não Encontrado
{ "statusCode" : 404 , "message" : "Servidor não encontrado" , "error" : "Not Found" }
Solução : Verifique se o ID do servidor está corretoRate Limiting A API implementa limitação de taxa para proteger contra abuso:
{ "statusCode" : 429 , "message" : "Muitas requisições. Tente novamente em 60 segundos" , "error" : "Too Many Requests" , "retryAfter" : 60 }
X-RateLimit-Limit: 100 X-RateLimit-Remaining: 99 X-RateLimit-Reset: 1642234800
Tratamento de Erros no Cliente JavaScript/TypeScript async function apiRequest ( url , options = {}) { try { const response = await fetch ( url , { headers: { 'Authorization' : `Bearer ${ token } ` , 'Content-Type' : 'application/json' , ... options . headers }, ... options }); if ( ! response . ok ) { const error = await response . json (); switch ( response . status ) { case 401 : // Token expirado, redirecionar para login window . location . href = '/login' ; break ; case 403 : throw new Error ( 'Permissão negada' ); case 404 : throw new Error ( 'Recurso não encontrado' ); case 422 : throw new Error ( error . message . join ( ', ' )); case 429 : // Rate limiting, aguardar antes de tentar novamente setTimeout (() => apiRequest ( url , options ), error . retryAfter * 1000 ); return ; default : throw new Error ( error . message || 'Erro desconhecido' ); } } return await response . json (); } catch ( error ) { console . error ( 'Erro na API:' , error ); throw error ; } }
Python import requests import time def api_request ( url , method = 'GET' , data = None , headers = None ): default_headers = { 'Authorization' : f 'Bearer { token } ' , 'Content-Type' : 'application/json' } if headers: default_headers.update(headers) try : response = requests.request(method, url, json = data, headers = default_headers) if response.status_code == 401 : # Token expirado, fazer novo login login() return api_request(url, method, data, headers) elif response.status_code == 403 : raise Exception ( 'Permissão negada' ) elif response.status_code == 404 : raise Exception ( 'Recurso não encontrado' ) elif response.status_code == 422 : error_data = response.json() messages = error_data.get( 'message' , []) raise Exception ( ', ' .join(messages) if isinstance (messages, list ) else messages) elif response.status_code == 429 : # Rate limiting retry_after = response.json().get( 'retryAfter' , 60 ) time.sleep(retry_after) return api_request(url, method, data, headers) response.raise_for_status() return response.json() except requests.exceptions.RequestException as e: print ( f 'Erro na requisição: { e } ' ) raise
Logs e Debugging Para debugging, a API fornece headers úteis nas respostas:
X-Request-ID: abc123-def456-ghi789 X-Response-Time: 150ms
Use o X-Request-ID ao reportar problemas para facilitar a investigação nos logs do servidor.
Melhores Práticas
Sempre trate erros : Implemente tratamento para todos os códigos de status possíveisRetry com backoff : Para erros 5xx, implemente retry com backoff exponencialRate limiting : Respeite os limites e implemente retry após o período especificadoLogs detalhados : Registre erros com contexto suficiente para debuggingFallbacks : Implemente comportamentos alternativos quando possível
Nunca exponha detalhes de erro internos para usuários finais. Sempre filtre informações sensíveis.
