server-errors

server-errors

Every failure a SiliconCompiler v1 orchestrator can return


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.

TypeStatusWhat it isWhat the client does
limit-exceeded429 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-denied403 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-provisioned403 Your account is not yet provisioned to run jobs here. Stops until an administrator provisions it.
not-permitted403 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-unavailable422 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-exceeded403 More nodes in one flow than allowed. Sends a smaller flow; waiting does not help.
upload-too-large413 Over max_upload_bytes, or any request body over its endpoint’s cap. Sends something smaller; waiting does not help.
download-too-large403 An object over the caller’s download ceiling. Does not refill. Fetches it through the portal.
declared-mismatch422 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-conflict409 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-accepted403 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-approved403 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-found404 It does not exist, or it is not yours — deliberately indistinguishable. Stops.
upload-digest-mismatch422 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-rejected422 The archive broke a limit or cannot be run as sent. reason names which. Fixes what reason names, in a new job.
invalid-token401 Expired or unverifiable access token. Refreshes, then retries once.
invalid-dpop-proof401 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-required401 The server requires a DPoP nonce and has just supplied one. Retries once with the nonce, and keeps one nonce per origin.
insufficient-scope403 The token is valid; its scope does not cover this call. Fails, and never refreshes.
invalid-request400 A malformed request. Often answered below the handler, untyped. Fixes the request.
insecure-transport426 A credential was offered over plaintext. Re-sends over https, and never downgrades.
rate-limited429 Calls per unit time. Waits Retry-After; that is the whole answer.
session-ended401 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-unsupported501 This deployment does not have the named capability now. Does not retry, and re-reads GET /v1 before offering it again.
not-ready409 An output the contract promises is not available yet. Waits Retry-After, then asks again.
invalid-cursor400 A stale or malformed ?cursor=. Restarts the pagination.
idempotency-key-reuse422 The same Idempotency-Key with a different request. Sends a fresh key.
resource-unavailable422 The job needs a resource this deployment does not hold and cannot supply. Stops: this deployment cannot run the job.
upload-forbidden422 The archive carries restricted material you may not upload. Removes the file, or references the resource, in a new job.
resource-unresolved422 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-unavailable422 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-allowed405 Wrong method for this path. Often answered below the handler, untyped. Fixes the request.
unsupported-media-type415 A Content-Type this endpoint does not accept. Often answered below the handler, untyped. Fixes the request.
not-acceptable406 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.

TypeCovered 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.