Tratamento de Erros da API
Este documento explica como os erros são representados na API do Dashboard.PT, os códigos de erro comuns, e estratégias para lidar com erros nas tuas aplicações.
Formato da Resposta de Erro
Quando ocorre um erro, a API devolve um código de estado HTTP apropriado e uma resposta JSON com detalhes:
Content-Type: application/json
{
"status": "error",
"message": "Invalid input",
"details": "Missing required field: graph_id"
}
Todas as respostas de erro incluem:
- status - Sempre "error" nas respostas de erro
- message - Uma mensagem de erro legível para humanos
- details - (Opcional) Informação mais específica sobre o erro
Códigos de Estado de Erro Comuns
| Código de Estado | Descrição | Causas Comuns |
|---|---|---|
| 400 Bad Request | Parâmetros ou corpo do pedido inválidos | Campos em falta, formato inválido, JSON malformado |
| 401 Unauthorized | Falha na autenticação | Chave de API inválida ou em falta |
| 403 Forbidden | Permissão negada | Aceder a um recurso que não te pertence, subscrição expirada |
| 404 Not Found | Recurso não encontrado | ID inválido, recurso eliminado |
| 429 Too Many Requests | Limite de pedidos excedido | Demasiados pedidos num dado período de tempo |
| 500 Internal Server Error | Erro do lado do servidor | Erros inesperados no servidor |
Erros de Validação
Quando a validação falha para os dados de entrada, a API devolve um estado 400 Bad Request com detalhes sobre o que falhou:
Content-Type: application/json
{
"status": "error",
"message": "Validation failed",
"details": {
"graph_id": "Required field is missing",
"data": "Must be an array with at least one element"
}
}
Erros de Frequência de Atualização
Quando tentas atualizar um gráfico com mais frequência do que a permitida pela sua configuração de frequência de atualização:
Content-Type: application/json
{
"status": "error",
"message": "Update not allowed based on frequency setting (daily)"
}
Nota
Para mais informações sobre frequências de atualização, consulta a documentação de Frequência de Atualização do Gráfico.
Boas Práticas de Tratamento de Erros
Quando trabalhas com a API do Dashboard.PT, segue estas boas práticas para o tratamento de erros:
- Verifica sempre os códigos de estado HTTP - Não confies apenas no corpo da resposta. Códigos de estado diferentes indicam tipos de erro diferentes.
- Implementa lógica de repetição - Para erros 429 (limite de pedidos) e da série 500, implementa backoff exponencial e lógica de repetição.
- Regista informação de erro detalhada - Inclui a resposta de erro completa nos teus registos para ajudar na depuração.
- Apresenta mensagens amigáveis para o utilizador - Traduz as mensagens de erro da API para linguagem acessível ao utilizador na tua aplicação.
- Procura detalhes específicos do erro - O campo "details" contém muitas vezes informação específica sobre o que correu mal.
Exemplos de Código para Tratamento de Erros
Exemplo em JavaScript
try {
const response = await fetch(`https://dashboard.pt/api/${endpoint}`, {
method,
headers: {
'Authorization': `Bearer ${apiKey}`,
'Content-Type': 'application/json'
},
body: data ? JSON.stringify(data) : null
});
const result = await response.json();
if (!response.ok) {
// Handle error response
console.error(`API Error (${response.status}):`, result);
// Handle specific status codes
if (response.status === 401) {
// Authentication error - redirect to login or refresh token
} else if (response.status === 429) {
// Rate limit exceeded - implement retry with backoff
}
throw new Error(result.message || 'API request failed');
}
return result;
} catch (error) {
console.error('Request failed:', error);
throw error;
}
}
Quer experimentar? O plano gratuito não tem limite de tempo.
Criar conta gratuita