Erro

Formato da Resposta de Erro

Todos os Endpoints retornam erros neste envelope unificado.

{
  "success": false,
  "error": {
    "code":    "INVALID_URL",
    "status":  400,
    "message": "The provided URL is not valid",
    "details": null
  }
}

Campos

• success (boolean): sempre false para erros
• error.code (string): código de erro legível por máquina — ver Códigos de erro
• error.status (number): código de status HTTP (espelha o status da resposta; útil quando o status bruto não está disponível)
• error.message (string): descrição legível do erro
• error.details (object | null): contexto estruturado do erro — por exemplo, erros de validação por campo como pares { field: message } retornados em INVALID_PARAMETER; null quando não aplicável

Tipo TypeScript

type ErrorResponse = {
  success: false;
  error: {
    code: string;       // machine-readable, e.g. "INVALID_URL"
    status: number;     // HTTP status code
    message: string;    // human-readable
    details: Record<string, unknown> | null;
  };
};

Contrato estável: estes 4 campos error.* são garantidos. Adições futuras manterão a retrocompatibilidade — os clientes podem ignorar campos desconhecidos com segurança.