Errors: what each code means¶

Every failure from the API carries a stable code. This page says what each one means and what to change.

Branch on code, not on the HTTP status and not on the message. Several codes share a status. The status tells a proxy what to do. The code tells the client what happened.

Each failure is an RFC 9457 problem document, sent as application/problem+json, and its type points at its code's section on this page. Messages are written for a person reading a log and may be reworded. The codes are a contract.

The catalogue¶

Code	HTTP status
`unauthorized`	401
`access_pending`	403
`forbidden`	403
`not_approved`	403
`terms_not_accepted`	403
`model_not_found`	404
`not_found`	404
`idempotency_conflict`	409
`job_not_cancelable`	409
`result_not_ready`	409
`upload_incomplete`	409
`result_expired`	410
`payload_too_large`	413
`bulk_rna_coverage_too_low`	422
`calibration_failed`	422
`checksum_mismatch`	422
`gene_ambiguous`	422
`gene_unknown`	422
`input_spec_mismatch`	422
`model_does_not_accept`	422
`unsupported_modality`	422
`validation_failed`	422
`quota_exceeded`	429
`rate_limited`	429
`internal`	500
`lane_disabled`	503
`queue_full`	503

What each one means¶

unauthorized¶

HTTP 401 · type ends in errors#unauthorized

No usable credential was presented. The key may be missing, malformed, revoked or expired.

access_pending¶

HTTP 403 · type ends in errors#access_pending

The account has asked for programmatic access, and the request is still open. Wait for the email: nothing else is needed.

forbidden¶

HTTP 403 · type ends in errors#forbidden

The credential is valid but its scopes do not include this operation.

not_approved¶

HTTP 403 · type ends in errors#not_approved

The account does not hold a grant of programmatic access, or no longer does. Access is requested in Aurora Intelligence, as Get access describes.

terms_not_accepted¶

HTTP 403 · type ends in errors#terms_not_accepted

The mint named a version of the Terms that is not the current one, or the key was minted under earlier Terms. The response names where to read the current Terms and what changed in them, and a key refused this way can still read the current version from GET /api-keys/terms. Mint a new key once you accept them.

model_not_found¶

HTTP 404 · type ends in errors#model_not_found

No model with that identifier is served. Identifiers include the release, and a retired release stops resolving.

not_found¶

HTTP 404 · type ends in errors#not_found

No resource of that kind with that identifier belongs to this account. A resource owned by someone else answers the same way, so that an identifier cannot be probed.

idempotency_conflict¶

HTTP 409 · type ends in errors#idempotency_conflict

The idempotency key has already been used with a different payload. Use a new key, or re-send the identical request.

job_not_cancelable¶

HTTP 409 · type ends in errors#job_not_cancelable

The job has already reached a terminal state and cannot be canceled.

result_not_ready¶

HTTP 409 · type ends in errors#result_not_ready

The job has not succeeded, so there is no result to download.

upload_incomplete¶

HTTP 409 · type ends in errors#upload_incomplete

The upload has not been completed, so it cannot be submitted yet. Finish the parts, then complete it.

result_expired¶

HTTP 410 · type ends in errors#result_expired

The retention window for this result has passed and the file has been deleted.

payload_too_large¶

HTTP 413 · type ends in errors#payload_too_large

The request exceeds a documented cap, which the problem document names. Limits states every cap.

bulk_rna_coverage_too_low¶

HTTP 422 · type ends in errors#bulk_rna_coverage_too_low

The bulk RNA profile covers too few of the model's genes to be used, so it is refused. The missing genes are not filled in for you. The problem document states how many it needs.

calibration_failed¶

HTTP 422 · type ends in errors#calibration_failed

The submitted embeddings were not produced the way this model reads them. Re-run the embedding with the package against the model's card. auroraomics doctor --model checks a machine first.

checksum_mismatch¶

HTTP 422 · type ends in errors#checksum_mismatch

The bytes received for an upload part do not hash to the digest that was declared for them. Re-send the part.

gene_ambiguous¶

HTTP 422 · type ends in errors#gene_ambiguous

A gene name in the request resolves to more than one identifier. Send the identifier.

gene_unknown¶

HTTP 422 · type ends in errors#gene_unknown

A gene name in the request is not in the gene table. Resolve it first. The table is versioned and includes previous symbols and aliases.

input_spec_mismatch¶

HTTP 422 · type ends in errors#input_spec_mismatch

The submission and the model's input_spec disagree on a field, which the problem document names. Re-prepare the input against the model's spec.

model_does_not_accept¶

HTTP 422 · type ends in errors#model_does_not_accept

The model's card does not declare the observation or covariate kinds this submission carries. The problem document's hint names what this model does accept. Another model in the catalogue may take the input as it is.

unsupported_modality¶

HTTP 422 · type ends in errors#unsupported_modality

No model this service runs takes that kind of input at all, so choosing a different model will not help. Check GET /v1/models: the catalogue's accepts is the whole of what can be submitted. This is not model_does_not_accept, which is one model declining a kind another model takes.

validation_failed¶

HTTP 422 · type ends in errors#validation_failed

The request did not satisfy the schema. The problem document names the field.

quota_exceeded¶

HTTP 429 · type ends in errors#quota_exceeded

A counter for this key has reached its limit for the window. The response names the counter, how much of it is used, and its window. The counter starts again on the next calendar day or month in UTC.

rate_limited¶

HTTP 429 · type ends in errors#rate_limited

Too many requests in too short a window. Wait for the seconds in Retry-After, then retry.

internal¶

HTTP 500 · type ends in errors#internal

The failure is in the service, not in the request. The response carries a request identifier. Quote it in a report.

lane_disabled¶

HTTP 503 · type ends in errors#lane_disabled

The runtime this model needs is not currently accepting work.

queue_full¶

HTTP 503 · type ends in errors#queue_full

The model's runtime is already holding as much waiting work as the service will queue, so the submission was refused rather than queued. Nothing was charged and no job was created. Wait for the seconds in Retry-After and send the same request again, with the same Idempotency-Key if you used one. quota_exceeded is the code about the key's own allowance.

What every error carries¶

Field	What it holds
`type`	the address of the code's section on this page
`title`	the code, in words
`status`	the HTTP status, which the code is always sent with
`code`	the stable code from the catalogue: branch on this
`detail`	what was wrong with this request, when there is more to say
`param`	the field at fault, when there is one
`hint`	what to do next
`request_id`	the request identifier, also sent as the `X-Request-Id` header: quote it in a report

Quote the request identifier in any report: it is how a failure is looked up without being reproduced. A 429 or a 503 also carries Retry-After.