> ## Documentation Index
> Fetch the complete documentation index at: https://docs.datawiz.io/connector-api/llms.txt
> Use this file to discover all available pages before exploring further.

# API responses

> Per-endpoint HTTP status codes and response bodies

All client endpoints require `Authorization` and `Client-Id` unless noted otherwise. Error bodies use FastAPI's standard `{"detail": ...}` wrapper except `initialize-session` conflicts (409), which return a flat JSON object.

Base path: `/api/v1/uploading`

## Common auth errors

| HTTP  | When                  | Body                                        |
| ----- | --------------------- | ------------------------------------------- |
| `401` | Missing/invalid token | `{"detail": "User not authenticated"}`      |
| `400` | Missing `Client-Id`   | `{"detail": "Client-ID header is missing"}` |

## Session access

Applies to endpoints that include `upload_uuid` in the path (all except **Get session status**).

| HTTP  | When                           | Body                                           |
| ----- | ------------------------------ | ---------------------------------------------- |
| `400` | No active session for client   | `{"detail": "Upload session not initialized"}` |
| `403` | `upload_uuid` ≠ active session | `{"detail": "Invalid upload UUID"}`            |

## Wrong session status (409)

Used by **Delete session**, **Upload entity**, and **Start upload** when the session is not `UPLOADING`:

```json theme={null}
{
  "detail": {
    "message": "Invalid upload session status",
    "expected": "UPLOADING",
    "actual": "DONE"
  }
}
```

***

## Initialize session

```http theme={null}
POST /api/v1/uploading/initialize-session
```

### 200 — created

New session:

```json theme={null}
{
  "status": "created",
  "upload_uuid": "b3f1...c9",
  "message": "Upload session created"
}
```

After previous `DONE` session:

```json theme={null}
{
  "status": "created",
  "upload_uuid": "new-uuid",
  "previous_upload_uuid": "old-uuid",
  "message": "Previous upload completed. New session created."
}
```

### 409 — conflict

Flat body (not wrapped in `detail`):

```json theme={null}
{
  "status": "already_exists",
  "session_status": "UPLOADING",
  "upload_uuid": "b3f1...c9",
  "message": "Upload session already exists"
}
```

```json theme={null}
{
  "status": "workflow_running",
  "session_status": "STARTED",
  "upload_uuid": "b3f1...c9",
  "message": "Connector workflow is running for this upload session"
}
```

***

## Get session status

```http theme={null}
GET /api/v1/uploading/{upload_uuid}/status
```

Does **not** check the active session — returns data for any `upload_uuid` stored for the client, or `404` if no record exists.

### 200

```json theme={null}
{
  "upload_uuid": "b3f1...c9",
  "session_status": "UPLOADING",
  "entities": ["receipts", "receipt-items"],
  "upload_tasks_finished": true,
  "can_upload_entities": true,
  "can_start_upload": true,
  "can_terminate": false
}
```

### 404

No PostgreSQL record and no Redis state:

```json theme={null}
{"detail": "Upload session not found"}
```

***

## Start upload

```http theme={null}
POST /api/v1/uploading/{upload_uuid}/start-upload
```

### 200

JSON from the Connector service (schema varies; may include extra fields).

### 400

| Cause                   | `detail`                                        |
| ----------------------- | ----------------------------------------------- |
| Session not initialized | `"Upload session not initialized"`              |
| `date_from` too early   | `"date_from cannot be earlier than YYYY-MM-DD"` |
| No entities uploaded    | `"No entities were uploaded in this session"`   |

### 409

| Cause                        | Body                                                         |
| ---------------------------- | ------------------------------------------------------------ |
| Session not `UPLOADING`      | Structured `detail` (see above)                              |
| Background S3 writes running | `{"detail": "Upload tasks are still in progress"}`           |
| Connector rejected start     | `{"detail": "<Connector response text or support message>"}` |

### 422

Invalid `date_from` / `date_to` in body — Pydantic validation array in `detail`.

### 502

```json theme={null}
{"detail": "Failed to connect to Connector service"}
```

Other Connector HTTP errors forward the Connector status code (e.g. `500`) with string `detail`.

***

## Delete session

```http theme={null}
POST /api/v1/uploading/{upload_uuid}/delete
```

### 200

```json theme={null}
{
  "status": "started",
  "message": "Upload deletion started"
}
```

### 409

Session not `UPLOADING` — structured `detail` (see above).

***

## Terminate workflow

```http theme={null}
POST /api/v1/uploading/{upload_uuid}/terminate
```

Allowed only when `session_status = STARTED`. The session returns to `UPLOADING` **asynchronously** after Connector sends the `upload-finished` webhook with `is_terminated=true`.

### 200

```json theme={null}
{
  "status": "started",
  "message": "Workflow stop requested. Session returns to UPLOADING after Connector confirms cancellation."
}
```

### 404

| Cause                        | `detail`                    |
| ---------------------------- | --------------------------- |
| Session not `STARTED`        | `"Workflow is not running"` |
| Connector workflow not found | `"Failed to stop workflow"` |

### 409 / 502 / 500

From Connector: `{"detail": "Failed to stop workflow"}` or connection error `{"detail": "Failed to connect to Connector service"}`.

***

## Upload entity

```http theme={null}
POST /api/v1/uploading/{upload_uuid}/{entity_name}
```

### 200

```json theme={null}
{
  "status": "success",
  "message": "Data validated successfully.",
  "rows_processed": 1500
}
```

### 400

```json theme={null}
{"detail": "Unknown entity: foo"}
```

### 409

Session not `UPLOADING` — structured `detail`.

### 422

String message in `detail`, for example:

* `"Invalid JSON format."`
* `"Missing required columns: store_id, receipt_id"`
* `"Unknown column: foo"`
* `"Invalid data types in payload: ..."`
* `"The columns array cannot be empty."`

***

## Proxy-level errors

| HTTP  | When                                        |
| ----- | ------------------------------------------- |
| `413` | Body exceeds 32 MB (ingest) or 1 MB (other) |
| `503` | Rate limit or connection limit              |