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:

HTTP/1.1 400 Bad Request
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:

HTTP/1.1 400 Bad Request
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:

HTTP/1.1 429 Too Many Requests
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:

  1. 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.
  2. 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.
  3. Regista informação de erro detalhada - Inclui a resposta de erro completa nos teus registos para ajudar na depuração.
  4. Apresenta mensagens amigáveis para o utilizador - Traduz as mensagens de erro da API para linguagem acessível ao utilizador na tua aplicação.
  5. 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

async function makeApiRequest(endpoint, method = 'GET', data = null) {
  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