Error

Forma della risposta di errore

Tutti gli endpoint restituiscono errori in questa envelope unificata.

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

Campi

• success (boolean): sempre false per gli errori
• error.code (string): codice di errore leggibile dalla macchina — vedi Codici di errore
• error.status (number): codice di stato HTTP (rispecchia lo stato della risposta; utile se lo stato grezzo non è accessibile)
• error.message (string): descrizione leggibile dell'errore
• error.details (object | null): contesto strutturato dell'errore — per esempio, errori di validazione a livello di campo come coppie { field: message } restituite su INVALID_PARAMETER; null quando non applicabile

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;
  };
};

Contratto stabile: questi 4 campi error.* sono garantiti. Le aggiunte future restano retrocompatibili — i client possono ignorare i campi sconosciuti in sicurezza.