Error

Error Response Shape

All endpoints return errors in this unified envelope.

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

Fields

• success (boolean): always false for errors
• error.code (string): machine-readable error code — see Error Codes
• error.status (number): HTTP status code (mirrors the response status; useful when the raw status is not available to the client)
• error.message (string): human-readable error description
• error.details (object | null): structured context — for example, field-level validation errors as { field: message } pairs returned on INVALID_PARAMETER; null when not applicable

TypeScript type

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

Stable contract: these four error.* fields are guaranteed. Future additions stay backward-compatible — clients can safely ignore unknown fields.