Errors¶

Every failure from the API is an RFC 9457 problem document, sent as application/problem+json, carrying a stable code from the catalogue below. The document's type points at the section for that code on this page, so an error can be read by following its own link.

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 you. Messages are written for a human reading a log and may be reworded; the codes are a contract.

A problem document also carries the request identifier from the response's request-id header. Quote it in any report: it is how a failure gets looked up without you having to reproduce it.

The catalogue¶

Code	HTTP status
`unauthorized`	401
`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.

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 behind this key has not been approved for programmatic access.

terms_not_accepted¶

HTTP 403 · type ends in errors#terms_not_accepted

The current Terms have not been accepted by this account.

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 key. 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 reached a terminal state, 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 or the part exceeds the documented cap. The cap is enforced before the bytes are written, not after.

bulk_rna_coverage_too_low¶

HTTP 422 · type ends in errors#bulk_rna_coverage_too_low

The bulk table covers too few of the model's input genes to be informative, so it is refused rather than silently padded.

calibration_failed¶

HTTP 422 · type ends in errors#calibration_failed

The submitted embeddings could not be reconciled with the encoder's calibration reference, so the model would be reading them in the wrong units.

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 instead of the symbol.

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.

unsupported_modality¶

HTTP 422 · type ends in errors#unsupported_modality

The kind of input named in the request is not one this API accepts.

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 says which counter and when it resets.

rate_limited¶

HTTP 429 · type ends in errors#rate_limited

Too many requests in too short a window. Wait for the interval the response gives.

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 rather than retrying blindly.

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 queue is at its bound. Retry after the interval the response gives.

What is never in an error¶

An error body says what was wrong with the request. It does not name a configuration value, a file on a server, or anything about how the service is put together — not as a courtesy, but because that is the kind of detail an error body has historically leaked to whoever was probing for it.