Errors¶

Endpoint errors come back as RFC 9457 problem+json, with the keys in alphabetical order:

{
  "detail": "unknown model 'nope'. Choose one of ['af2ig', 'boltz2', 'esmfold2', 'esmfold2-fast', 'openbind', 'opendde', 'opendde-abag', 'openfold3', 'rf3'].",
  "instance": "/v1/predictions",
  "status": 400,
  "title": "Invalid request",
  "type": "https://japanfold.aiand.com/errors/invalid-input"
}

detail: specific explanation of this failure. Read this first.
instance: the request path that failed.
status: the HTTP status, mirrored in the body.
title: short, human-readable summary.
type: a URI categorizing the error (may be about:blank).

Every response, error or not, carries an X-Request-Id header. When you report a problem, send it along with the job id and we can find that exact request. You can also send your own X-Request-Id (8 to 64 letters, digits, ., _ or -) and we use it instead.

Status codes¶

Code	Meaning	What to do
`400`	Invalid request: bad params, malformed input, or over a size cap (residues, chains, input length).	Fix the request; read `detail`. See Models & limits.
`401`	No key, or a key that is invalid or revoked. Every route but the catalog needs one.	Send `Authorization: Bearer $JAPANFOLD_API_KEY`. No key yet: sign in at your account to make one.
`403`	A key was used to manage keys or change the account. Those take a signed-in browser.	Do it on your account.
`402`	The balance is spent. `out_of_credit` is `true` and `detail` carries a link to top up. A job already queued still runs.	Add funds on your account. Retrying sooner does not help.
`404`	No such job, or a job you don't own.	Check the id; jobs are scoped to their owner.
`422`	An `Idempotency-Key` you already used, sent with a different body. `detail` names the first job.	Use a new key for a new submission.
`429`	Too many sign-in codes for one address or network, or too many contact messages. Nothing rations folding.	Honor the `Retry-After` header, then retry.
`413`	Request body over 8 MiB.	Shrink the input; you're almost certainly over `max_content_chars` anyway (see Models & limits).
`503`	The accelerators are offline for maintenance, or none of them serves the model you asked for, so no job can start.	Honor the `Retry-After` header (5 minutes) and retry. Nothing is wrong with your request.

Handling 503 (maintenance)¶

A busy fleet is not an error: your job is admitted and waits its turn, and every account with work waiting gets an equal share of the chips. 503 is the different case, where no Galaxy serves the model you asked for, so the job would wait for nothing and submitting again immediately cannot succeed:

{
  "type":   "https://japanfold.aiand.com/errors/unavailable",
  "title":  "Service Unavailable",
  "status": 503,
  "detail": "No Galaxy serves boltz2 right now, so this job would wait for nothing. Choose another model or try again later.",
  "instance": "/v1/predictions"
}

Only job creation (/v1/predictions, /v1/designs, /v1/embeddings) returns it. When nothing at all is online, a job is still accepted and waits with queue.reason no_galaxy_online (see Jobs). Reading jobs and downloading results keep working, so anything you submitted earlier stays available.

Every response is problem+json, including a 404 on a path that does not exist, a 405 for the wrong HTTP method on one that does (a GET on /v1/predictions, /v1/designs or /v1/embeddings), and a 500. A 404 on a path that does not exist lists the routes it most likely meant in did_you_mean (/models names /v1/models).

Submission too large¶

A 400 whose type is .../errors/submission-too-large is not a bad request. Every field in it is legal; what it exceeds is what the job would write. The one output cap is max_output_bytes_per_job, 640 MB, and only embeddings come near it.

{
  "detail": "This submission would produce about 748 MB of embeddings (50 sequences x 1968 residues), and the limit is 640 MB per submission. Send fewer or shorter sequences: ESMC-6B writes 7.7 kB per residue.",
  "instance": "/v1/embeddings",
  "status": 400,
  "title": "Submission too large",
  "type": "https://japanfold.aiand.com/errors/submission-too-large"
}

detail names the shape that was measured and what to lower.

Large bodies¶

The body cap is 8 MiB, and it sits above the input caps, so an oversized input usually fails validation with a 400 first: an 8.2 MB request comes back as a problem+json 400 naming max_content_chars. Only past 8 MiB do you get the 413, which is problem+json like every other refusal.