Errors¶
Errors come back as RFC 9457 problem+json:
{
"type": "https://japanfold.com/errors/invalid-input",
"title": "Invalid request",
"status": 400,
"detail": "unknown model 'nope' — choose one of ['boltz2', 'esmfold2', 'esmfold2-fast', 'openfold3', 'opendde', 'opendde-abag', 'protenix-v2'].",
"instance": "/v1/predictions"
}
title: short, human-readable summary.detail: specific explanation of this failure (read this first).status: the HTTP status, mirrored in the body.type: a URI categorizing the error (may beabout:blank).instance: the request path that failed.
Status codes¶
| Code | Meaning | What to do |
|---|---|---|
400 |
Invalid request: bad params, malformed input, or over a size cap (residues, chains, designs, …). | Fix the request; read detail. See Models & limits. |
401 |
Missing/invalid credentials for an authenticated action. | Check your Authorization: Bearer key. |
403 |
Forbidden. | See the Cloudflare note below if detail mentions error 1010. |
404 |
No such job, or a job you don't own. | Check the id; jobs are scoped to their owner. |
413 |
Request body over 8 MB. | Shrink the input; you're almost certainly over max_content_chars anyway (see Models & limits). |
429 |
At capacity or over a rate limit. | Honor the Retry-After header, then retry. See the limits page. |
503 |
The accelerators are offline for maintenance, so no job can start. | Honor the Retry-After header (5 minutes) and retry. Nothing is wrong with your request. |
Handling 429 (at capacity)¶
When the service is busy, or you exceed a submit or active-job quota, you get
429 with a Retry-After header in seconds. Wait that long and retry, backing
off if it repeats.
resp=$(curl -s -D /tmp/h -o /tmp/b -w '%{http_code}' -X POST \
https://api.japanfold.com/v1/predictions -H 'Content-Type: application/json' \
-d '{"model":"boltz2","sequence":"MKTAYIAK..."}')
if [ "$resp" = "429" ]; then
sleep "$(grep -i '^retry-after:' /tmp/h | tr -dc 0-9)"
# retry...
fi
Handling 503 (maintenance)¶
429 and 503 mean different things. 429 is a queue: the hardware is running
and your turn is coming. 503 means there is no hardware to run on at that
moment, so submitting again immediately cannot succeed:
{
"type": "https://japanfold.com/errors/unavailable",
"title": "Service Unavailable",
"status": 503,
"detail": "JapanFold's accelerators are offline for maintenance right now, so no jobs can start. Please try again in a few minutes.",
"instance": "/v1/predictions"
}
Only job creation (/v1/predictions, /v1/designs, /v1/embeddings) returns
it. Reading jobs and downloading results keep working, so anything you submitted
earlier stays available.
Cloudflare 403 / error 1010¶
A 403 whose body references Cloudflare error 1010 is edge-level bot
filtering of your HTTP client, not an API error. Retry the identical request with
a browser-like User-Agent: