API responses - Connector API

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:

{
  "detail": {
    "message": "Invalid upload session status",
    "expected": "UPLOADING",
    "actual": "DONE"
  }
}

Initialize session

POST /api/v1/uploading/initialize-session

200 — created

New session:

{
  "status": "created",
  "upload_uuid": "b3f1...c9",
  "message": "Upload session created"
}

After previous DONE session:

{
  "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):

{
  "status": "already_exists",
  "session_status": "UPLOADING",
  "upload_uuid": "b3f1...c9",
  "message": "Upload session already exists"
}

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

Get session status

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

{
  "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:

{"detail": "Upload session not found"}

Start upload

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

{"detail": "Failed to connect to Connector service"}

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

Delete session

POST /api/v1/uploading/{upload_uuid}/delete

200

{
  "status": "started",
  "message": "Upload deletion started"
}

409

Session not UPLOADING — structured detail (see above).

Terminate workflow

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

{
  "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

POST /api/v1/uploading/{upload_uuid}/{entity_name}

200

{
  "status": "success",
  "message": "Data validated successfully.",
  "rows_processed": 1500
}

400

{"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

​Common auth errors

​Session access

​Wrong session status (409)

​Initialize session

​200 — created

​409 — conflict

​Get session status

​200

​404

​Start upload

​200

​400

​409

​422

​502

​Delete session

​200

​409

​Terminate workflow

​200

​404

​409 / 502 / 500

​Upload entity

​200

​400

​409

​422

​Proxy-level errors

Common auth errors

Session access

Wrong session status (409)

Initialize session

200 — created

409 — conflict

Get session status

200

404

Start upload

200

400

409

422

502

Delete session

200

409

Terminate workflow

200

404

409 / 502 / 500

Upload entity

200

400

409

422

Proxy-level errors