API Error Reference¶

This reference matches the alpha3 OpenAPI schema exposed at /openapi.json. Route decorators now include concrete responses={...} metadata for success payloads and the documented error cases below.

Error Response Shapes¶

ApiError responses¶

These are raised by file_organizer.api.exceptions.ApiError and share a stable JSON shape:

{
  "error": "not_found",
  "message": "Path not found",
  "details": null
}

HTTPException responses¶

Some endpoints still use FastAPI's built-in HTTPException shape:

{
  "detail": "Incorrect username or password"
}

Validation responses¶

Request parsing and schema validation failures return:

{
  "error": "validation_error",
  "message": "Invalid request payload.",
  "details": [
    {
      "loc": ["body", "path"],
      "msg": "Path must not be empty"
    }
  ]
}

Global status codes¶

Endpoint error codes¶

Health and daemon¶

Authentication¶

Files¶

Organization and deduplication¶

Search and analyze¶

Setup and configuration¶

Integrations, marketplace, and plugin API¶

OpenAPI examples¶

The generated OpenAPI schema now includes concrete examples for both successful and error responses on the highest-traffic REST routes:

• auth
• files
• organize
• dedupe
• search
• analyze
• system
• config
• setup

That gives API consumers one place to inspect machine-readable examples in /openapi.json and one place to review the error-code contract in prose.