Every error from a SiliconCompiler-compatible orchestrator is an
RFC 9457
application/problem+json body, and its type is the URL of this page, on the server that answered. You
are probably here because you dereferenced one.
{
"type": "https://sc.example.com/server-errors/entitlement-denied",
"title": "Not entitled to this resource",
"status": 403,
...
}
Clients branch on type, then on reason where the type defines
one. title and detail are prose and may be reworded in any
release — a client that string-matches them is broken by a typo fix. An unrecognised
reason means act on the type alone. The type URI is frozen for
the life of v1.
Not every failure has a type. The guarantee covers what a
/v1 request handler produced. A stopped process, a proxy refusing an oversized body, or
a routing-level rejection can answer first, with the web server’s own HTML. Inspect
Content-Type, treat a non-problem+json non-2xx as an untyped failure of its
status class, and never assume type exists. A 5xx is handled by its status,
honouring Retry-After.
Two endpoints answer in another shape. POST /v1/auth/token and
POST /v1/auth/device answer what OAuth processing refuses in the OAuth shape —
error, error_description and reason — and only the
transport-level refusals there, raised before any OAuth processing, are problem+json:
insecure-transport,
rate-limited,
unsupported-media-type and
method-not-allowed.
Every type
All 38, grouped by kind. Each links to its page. A refusal is retryable by waiting if and only
if it carries Retry-After.
| Type | Status | What it is | What the client does |
|---|---|---|---|
limit-exceeded | 429 |
A ceiling that refills. limit names which; pending_uploads also carries job_ids. |
Waits Retry-After, then retries. On pending_uploads it may cancel a job in job_ids it will not submit; an empty job_ids means jobs this session cannot read hold the slots. |
entitlement-denied | 403 |
No grant for a PDK, tool, library or FPGA device the job names or an artifact derives from. | Stops; the person asks for a grant, on the page POST /v1/auth/browser answers for the resource, from an interactive session. |
account-not-provisioned | 403 |
Your account is not yet provisioned to run jobs here. | Stops until an administrator provisions it. |
not-permitted | 403 |
A write on a job you can read and may not act on, or a create naming an archived project. | Stops, and does not offer that action on that job again. |
software-unavailable | 422 |
No image satisfies the job’s software, SiliconCompiler’s own version included. Names every requirement that failed. | Asks for a version in available, or asks the operator. |
node-limit-exceeded | 403 |
More nodes in one flow than allowed. | Sends a smaller flow; waiting does not help. |
upload-too-large | 413 |
Over max_upload_bytes, or any request body over its endpoint’s cap. |
Sends something smaller; waiting does not help. |
download-too-large | 403 |
An object over the caller’s download ceiling. Does not refill. | Fetches it through the portal. |
declared-mismatch | 422 |
The manifest’s design, job name or SiliconCompiler version disagrees with the job. | Reports a client bug; resubmitting unchanged fails the same way. |
job-state-conflict | 409 |
The job’s state does not allow that call; reason: "in_progress" for a retry the server is still handling. |
Re-reads the job. On in_progress, waits Retry-After and retries with the same key. |
terms-not-accepted | 403 |
An unaccepted terms document. blocked_by lists each one by its terms id. |
Opens each document’s page from POST /v1/auth/browser, then retries. |
artifact-not-approved | 403 |
The per-object gate withholds the artifact. Also a rejected job’s error: it continues from a job whose results the gate withholds from everyone. |
Asks at the page POST /v1/auth/browser answers for the artifact, where can_request_access is true; otherwise stops. |
not-found | 404 |
It does not exist, or it is not yours — deliberately indistinguishable. | Stops. |
upload-digest-mismatch | 422 |
The digest is not the one the grant bound, or the upload does not match it. | Uploads the archive whose digest the grant bound, then submits again. |
archive-rejected | 422 |
The archive broke a limit or cannot be run as sent. reason names which. |
Fixes what reason names, in a new job. |
invalid-token | 401 |
Expired or unverifiable access token. | Refreshes, then retries once. |
invalid-dpop-proof | 401 |
The DPoP proof was malformed, replayed or wrongly keyed. | Fails, and does not refresh; refused for its time, corrects its clock and retries once. |
dpop-nonce-required | 401 |
The server requires a DPoP nonce and has just supplied one. | Retries once with the nonce, and keeps one nonce per origin. |
insufficient-scope | 403 |
The token is valid; its scope does not cover this call. | Fails, and never refreshes. |
invalid-request | 400 |
A malformed request. Often answered below the handler, untyped. | Fixes the request. |
insecure-transport | 426 |
A credential was offered over plaintext. | Re-sends over https, and never downgrades. |
rate-limited | 429 |
Calls per unit time. | Waits Retry-After; that is the whole answer. |
session-ended | 401 |
The session is over. reason says why. |
Re-authenticates and never refreshes. On reused, says the credentials were used elsewhere. |
run-interrupted | — | Never an HTTP response. The environment ended the run. | May resubmit unchanged, and it may work. |
staging-failed | — | Never an HTTP response. The server could not get the job ready, for its own reasons. | Submits again later. |
staging-timed-out | — | Never an HTTP response. Staging ran past the caller’s max_staging_seconds. limit names it. |
Reports the limit, and sends a smaller package set or asks the operator: unchanged, it times out again. |
run-failed | — | Never an HTTP response. The run failed in a way resubmitting unchanged repeats. | Changes something before it resubmits. |
feature-unsupported | 501 |
This deployment does not have the named capability now. | Does not retry, and re-reads GET /v1 before offering it again. |
not-ready | 409 |
An output the contract promises is not available yet. | Waits Retry-After, then asks again. |
invalid-cursor | 400 |
A stale or malformed ?cursor=. |
Restarts the pagination. |
idempotency-key-reuse | 422 |
The same Idempotency-Key with a different request. |
Sends a fresh key. |
resource-unavailable | 422 |
The job needs a resource this deployment does not hold and cannot supply. | Stops: this deployment cannot run the job. |
upload-forbidden | 422 |
The archive carries restricted material you may not upload. | Removes the file, or references the resource, in a new job. |
resource-unresolved | 422 |
The server could not decide what the flow needs: an ASIC project with no PDK set. | Sets the PDK, in a new job. |
prior-results-unavailable | 422 |
A continues_from entry names results that cannot be used. reason says why. |
Runs from an earlier step, or names a job of its own whose results can be used. |
method-not-allowed | 405 |
Wrong method for this path. Often answered below the handler, untyped. | Fixes the request. |
unsupported-media-type | 415 |
A Content-Type this endpoint does not accept. Often answered below the handler, untyped. |
Fixes the request. |
not-acceptable | 406 |
No representation satisfies your Accept. Often answered below the handler, untyped. |
Fixes the request. |
Retired
Retired, never raised, and not to be reused. They have no page.
| Type | Covered now by |
|---|---|
unsatisfiable-request, version-skew, too-many-attempts, scheduler-lost |
resource-unavailable covers every resource kind;
software-unavailable covers images and SiliconCompiler’s own version, and
declared-mismatch a manifest that disagrees with it;
the approval page caps wrong guesses per approver;
run-interrupted is a run the environment ended. |
Stability
The registry is complete at the v1 freeze. A type may gain extension members
— that is additive, and an unrecognised member is ignored, never an error. Changing what a
member means, or retiring a URI, costs a major version.
The URIs are identical on every deployment, whether you are talking to the reference
sc-server or a commercial orchestrator. That is the property the registry exists for: a
client switching between them needs one table, not two.