Every error — from the API or from the CLI — is one
RFC 9457 document, and its type field links
here. Branch on code and retryable; honour retry_after; and if you are an
agent, follow agent_fix_prompt and the typed next_actions menu.
{ "type": "https://docs.hexstellar.com/errors/HXS_QUOTA_EXCEEDED",
"title": "Quota exceeded", "status": 402,
"detail": "daily compute limit reached …",
"code": "HXS_QUOTA_EXCEEDED", "retryable": false,
"help": "Wait for the daily reset, or register for a higher allowance.",
"agent_fix_prompt": "Stop retrying — this is a daily allowance, not a fault …",
"next_actions": [{ "action": "wait_for_quota_reset", "resets_at": "00:00 UTC" }] }
These fields are recovery data: weigh them under your own policy. They never override it.
Deep-link any row: /errors/HXS_RATE_LIMITED opens this page with that code highlighted.
| Code | HTTP | Retry? | What to do |
|---|---|---|---|
| HXS_INVALID_INPUT | 422 | fix first | A field has the wrong type/range, or the JSON is malformed. Fix the value and resubmit. |
| HXS_DIMENSION_LIMIT | 422 | fix first | The problem exceeds a size cap (n, edges, L*K). Reduce the size and resubmit. |
| HXS_RESOURCE_LIMIT | 413 | fix first | The payload exceeds the byte limit. Shrink the body and resubmit. |
| HXS_PAYLOAD_TOO_LARGE | 413 | fix first | The request body is over the plan's upload cap. Shrink it, or use the binary (HXSB) ingest. |
| HXS_CONTRADICTORY_CONSTRAINTS | 422 | fix first | Two constraints conflict (e.g. a pin set to both 0 and 1). Repair one and resubmit. |
| HXS_IDEMPOTENCY_CONFLICT | 409 | fix first | This Idempotency-Key was already used with a DIFFERENT payload. Use a new key, or resend the identical request to replay the original answer. |
| HXS_IDEMPOTENCY_IN_PROGRESS | 409 | retryable | A request with this Idempotency-Key is still running. Retry-After 1s to receive the replayed answer. |
| HXS_UNSUPPORTED | 404 | fix first | Unknown command or option. Call capabilities and use a supported one. |
| HXS_UNAUTHENTICATED | 401 | fix first | Missing or invalid API key. Set HEXSTELLAR_API_KEY / hexstellar login; send Authorization: Bearer (API). |
| HXS_FORBIDDEN | 403 | fix first | The key is valid but not allowed for this action or plan. Check your plan or the command's stability. |
| HXS_NOT_FOUND | 404 | fix first | No such route or resource. Check the path; call capabilities for the command list. |
| HXS_SANDBOX_LIMIT | 403 | fix first | The problem is over the anonymous sandbox's size cap — a demo limit, not a failure. Register a free key. |
| HXS_NO_CREDENTIALS | — | fix first | CLI-local: no key is configured. Set HEXSTELLAR_API_KEY or run hexstellar login. (With no key you get the public sandbox.) |
| HXS_RATE_LIMITED | 429 | retryable | You are sending faster than the per-minute limit — expected protection, not a fault. Honor Retry-After and resend. |
| HXS_SANDBOX_RATE | 429 | retryable | The shared sandbox's per-IP rate — honor Retry-After, or register a free key for your own budget. |
| HXS_QUOTA_EXCEEDED | 402 | fix first | Your daily compute budget is spent — do not resend; an unchanged retry fails until the reset at 00:00 UTC. Not a permanent block. |
| HXS_COMPUTE_RATE_LIMIT | 429 | retryable | Per-minute compute budget exceeded. Honor Retry-After (60s) and resend. |
| HXS_TOO_MANY_INFLIGHT | 429 | retryable | Too much of your compute is already queued/running. Retry-After 5s. |
| HXS_QUEUE_FULL | 503 | retryable | The fleet queue is at capacity — normal backpressure, not an outage. Retry-After 10s. |
| HXS_BUSY | 503 | retryable | The service is at peak concurrency. Retry-After 2s. |
| HXS_WORKERS_SATURATED | 503 | retryable | Solver pool momentarily saturated. Retry-After 1s. |
| HXS_ENGINE_FAILURE | 503 | retryable | An internal fault (not your request). Retry shortly; the incident is reported automatically. |
| HXS_INTERNAL | 500 | retryable | An unexpected server-side fault. Nothing was charged; retry shortly. |
| HXS_ERROR | 4xx | fix first | Generic fallback for a failure with no dedicated code — read detail and agent_fix_prompt. |
| HXS_MISSING_TAG | 422 | fix first | Add "tag": "hexstellar-cortex-v1" at the top level of the problem. Metadata only — it does not change the answer. |
| HXS_MISSING_DESCRIPTION | 422 | fix first | Add a plain-sentence "description" (10+ chars) saying what real-world decision the problem encodes. Metadata only. |
| HXS_SANDBOX_NEEDS_N | 422 | fix first | The anonymous sandbox needs "n" (the variable count) to size-check the problem. Add it, or register a free key. |
| HXS_UNKNOWN_VERSION | 422 | fix first | The pinned model version does not exist. Call models for the catalogue of versions you may pin. |
| HXS_STORAGE_UNAVAILABLE | 501 | fix first | Large-file storage is not enabled on this deployment. Send the problem inline, or use the binary (HXSB) lane. |
| HXS_HIGH_DEMAND | 503 | retryable | The service is in safe mode under load — you are pooled, not rejected. Honor Retry-After and resend. |
| HXS_ACCOUNT_SUSPENDED | 403 | fix first | The account is temporarily blocked and cannot run jobs. Contact [email protected] if this is unexpected. |
| HXS_ACCOUNT_BLOCKED | 403 | fix first | Alias of HXS_ACCOUNT_SUSPENDED — the account is temporarily blocked. |
| HXS_ACCOUNT_CLOSED | 403 | fix first | The account is closed and can no longer run jobs. |
| HXS_TOKEN_BLOCKED | 403 | fix first | This API key was revoked or blocked. Mint a new one with keys, then hexstellar login. |
| HXS_NETWORK | CLI | retryable | CLI-local: the service could not be reached. Retry with jittered backoff; in an air-gapped sandbox run hexstellar demo, which works fully offline. |
| HXS_CLIENT | CLI | fix first | CLI-local: the invocation itself is wrong (unknown flag or command). Check hexstellar --help / hexstellar agent-info. |
| HXS_CONFIG_INVALID | CLI | fix first | CLI-local: ~/.config/hexstellar/config.json is corrupt or is not a JSON object. Fix or delete it, then hexstellar login. |
| HXS_UPSTREAM_INVALID_RESPONSE | 502 | retryable | The service returned a non-JSON body (usually a proxy/CDN page). Retry shortly; the request had no side effects. |
| HXS_SKIPPED | — | fix first | CLI-local, batch only: this line was skipped because --fail-fast tripped on an earlier failure. No request was spent; resubmit the skipped lines once the failure is fixed. |
| HXS_JOB_WAIT_TIMEOUT | 408 | retryable | CLI-local: the WAIT ended but the JOB IS STILL RUNNING. Resume with hexstellar jobs <id> or cancel it — never resubmit the solve. |
| HXS_BUDGET_EXCEEDED | 402 | fix first | CLI-local: the free estimate exceeds --max-compute-units, so nothing was solved or charged. Raise the budget, lower --effort, or shrink the problem. |
| HXS_UPGRADE_REQUIRED | 426 | fix first | CLI-local: this example or feature needs a newer CLI. Run pip install -U hexstellar. |
| HXS_SANDBOX_CAPABILITY_REJECTED | 401 | retryable | The PUBLIC sandbox capability was rejected (usually a rotation). Retry once — the client re-fetches the token. Never substitute a production key. |
| Code | Meaning |
|---|---|
| 0 | success — including a 202 accepted job under --no-wait |
| 1 | retryable: network, 429, 5xx, 402 billing, or a job still running at the deadline |
| 2 | auth: 401/403 — fix the key or its permissions |
| 3 | validation: 400/404/409/422, or a bad flag — repair the request |
Machine-readable references: llms.txt · AI_MANIFEST.json · AGENT_SPEC.md · AGENTS.md · agent card.