How a Request Flows

This page walks through the stages a /v1/forecast request passes, from the caller's point of view, and what each stage can return. The check-by-check order is in POST /v1/forecast.

1. Stages

Every request passes these checks in order. A check that passes moves on to the next stage; the errors listed are returned only when that check fails.

Stage	What happens	Returned if it fails
Authentication	Checks `Authorization: Bearer sqx_live_…` and the key's scope, then that the endpoint is not paused and the key's account or workspace is active; continues if so.	`INVALID_API_KEY`, `INSUFFICIENT_SCOPE`, `ACCOUNT_SUSPENDED`, `ORG_PENDING_DELETION`, 503 `SERVICE_UNAVAILABLE` (paused, with `Retry-After`)
Idempotency	With `Idempotency-Key`: claims the key, or returns the stored result of an identical, finished request (not billed again).	`VALIDATION_ERROR` (400), `IDEMPOTENCY_KEY_REUSED`, `IDEMPOTENCY_IN_PROGRESS`
Rate limit check	Counts this request toward the account's requests this minute (shared by all its keys); continues if under the limit.	429 `forecast-rpm`
Request validation	Parses JSON; checks fields, the per-request row cap (200,000 rows; an oversized request is refused, never queued) and cleaning options; continues if valid.	`MALFORMED_JSON`, `VALIDATION_ERROR`, `POINTS_EXCEEDED`, `CLEANING_OPTION_UNSUPPORTED`
Model selection	Confirms the model is available, `h` is within its maximum horizon and no entity is longer than its maximum context; continues if so.	`MODEL_NOT_AVAILABLE`, `MODEL_OPTION_UNSUPPORTED`, `HORIZON_EXCEEDS_MODEL`, `SERIES_TOO_LONG`, `SERVICE_UNAVAILABLE`
Quota reservation	Reserves "rows + `h` × entities" of today's points; continues if enough remain.	429 `forecast-daily-points`
Cleaning	Prepares the data under the effective preset and builds the cleaning report (the `raw` preset only runs a structural check); continues if it passes. Queues briefly while cleaning capacity is full.	`SERIES_DISCONTINUOUS`, `TIMESTAMP_IRREGULAR`, `FREQ_*`, `SERIES_TOO_SHORT`, `SERIES_TOO_LONG` (the cleaned grid is longer than the model's context), `RAW_INPUT_INVALID` and others; 503 `SERVICE_UNAVAILABLE` with `Retry-After` if the queue wait runs out (retry later)
Inference	Sends the cleaned series to the model for point forecasts and intervals.	`MODEL_BUSY`, `GATEWAY_TIMEOUT`, `SERVICE_UNAVAILABLE`
Settlement	Settles the reservation to the actual billable points and returns the response.	—

A failure at any stage releases the reserved points; error responses are never metered.

2. Recommended integration steps

Create a sqx_live_… key on the SequenxAI Platform and keep it in a server-side environment variable.
Dry-run with /v1/clean first to confirm frequency, time zone and cleaning decisions. This step is free.
Call /v1/forecast and log the response's request_id, effective_policy.id and usage.
Handle failures by error.code: fix the request on 422, retry after Retry-After on 429 and 503/504; see Error Codes.