Health
GET https://api.usenexio.com/health needs no API key and is not rate limited.
The HTTP status is 200 whenever the health handler answers, including when
status is degraded: database or queue trouble never changes the status code, so read the body. Like every route, /health passes through the shared request middleware, which answers 500 internal_error if the handler fails unexpectedly and 504 request_timeout if it runs past the 30-second request limit. Treat either as the API not answering. There is no /api/v1/health route.
Which build answered
Responses from the Records routes (/api/v1/records and below) carry the header X-Nexio-Engine-Build with the same commit as /health, when the build is stamped. Use it to key a cache to the build that produced the data. Responses refused before they reach those routes (401 for a bad key, 429 for a rate limit) do not carry it. Neither does a 504 request_timeout or a 500 internal_error written when the request times out or fails unexpectedly. Other route families do not send it.
Every response also carries x-request-id. Send your own x-request-id (1 to 128 printable ASCII characters, no spaces) and the API echoes it back and records it in its access log. A missing or invalid value is replaced by the request’s 32-character trace ID.
Deploys
Nexio deploys continuously: every change merged to its main branch goes to production after automated checks. A deploy counts as done only when production reports the new commit on/health and a production smoke test passes; otherwise it is rolled back automatically. The API has no maintenance mode, and deploys do not take it offline: a stopping API instance finishes its in-flight requests for up to 10 seconds before it exits.
Runs during a deploy
A run is processed by a worker. When a worker stops for a deploy, it gives each run a grace period to finish.
Run statuses and polling are defined on Runs.
Stuck and lost runs
Workers record a heartbeat on every run they process. Nexio’s worker checks for runs that stopped reporting:- A running run with no heartbeat for 3 minutes (15 minutes if it never reported one) is reclaimed and restarted once. It stays
processing. If it goes silent again, it fails and is not retried. - A run that no worker holds any more fails with the error “worker restarted: run did not complete” and
error_details.type: "pipeline_error". A matching engine’s run fails instead with an error of the formmatching run timed out during {stage} after its worker lease expiredanderror_details.type: "pipeline_timeout", with the stage inerror_details.stage. - A run with a pending cancel request is marked cancelled instead.
Idempotency-Key: sending the original key again returns the original failed run, because the key stays bound for as long as that run is stored (see Runs).
Cancelling a run
POST /api/v1/runs/{run_id}/cancel stops a run that is queued or processing.
- A queued run is cancelled at once: the response is 202 with
status: "cancelled". - A processing run is asked to stop: the response is 202 with
status: "processing"andcancel_requested_at. The worker checks for cancel requests every 2 seconds, then marks the run cancelled and sends therun.cancelledwebhook event. - A run that already finished answers 200 with its status fields and stored output, without
solutionsand the other fields onlyGET /api/v1/runs/{run_id}adds. Read the result withGET.
Failed deliveries and recovery
Rate limits and caps
The API limits requests per minute and can cap runs per month for an organization. A rate-limit refusal is429 rate_limited with a Retry-After header. A monthly cap refusal is 429 run_cap_exceeded with no Retry-After: it does not clear until the next month. Limits, defaults and the monthly run cap are on Limits and rate limits.
Escalate to Nexio
Email support@usenexio.com. Include:Runs
Statuses, polling, idempotency and cancellation.
Errors
Every error code and what to do about it.