Errors

Envelope

Every failed call returns a JSON body with the same shape, and the matching HTTP status.

{
  "error": {
    "code": "model_busy",
    "message": "model sam3 is busy; retry shortly",
    "retryable": true,
    "retryAfterMs": 5000
  }
}

Field	Meaning
code	A stable, machine-readable code. Branch on code, not on message.
message	A human-readable explanation. The wording can change.
retryable	true when repeating the same request unchanged can succeed.
retryAfterMs	Suggested wait in milliseconds. 0 when there is no hint.

429 and 503 responses also carry a Retry-After header in whole seconds.

A failed call costs 0 credits. Nothing is charged when a call returns an error.

Codes

Status	Code	Retryable	Meaning
400	invalid_request	No	The request is malformed, a field is out of range, or the image fails the upload checks.
400	invalid_image	No	The image passed the upload checks but could not be decoded. The same handle keeps answering this code.
400	unsupported	No	The request is valid but uses something not available yet, such as image.url.
401	unauthorized	No	The API key is missing, malformed, invalid, expired or revoked.
402	insufficient_balance	No	The balance cannot cover the price of the call.
403	model_locked	No	The key’s scope or the account’s pool does not allow the model.
403	email_unverified	No	The key owner has not verified an email address.
404	not_found	No	The path does not exist.
404	image_not_found	No	The img_ handle is unknown, expired or evicted. Upload the image again.
409	idempotency_conflict	No	The Idempotency-Key was used with a different request body.
409	request_in_progress	No	The first request with this Idempotency-Key is still running.
413	payload_too_large	No	The request body or the image exceeds the size limit.
429	rate_limited	Yes	The per-minute limit of the pool was reached (funded accounts: only when the balance cannot pay for the call).
429	daily_limit_reached	No	The daily allowance of the public pool is used up.
500	internal_error	No	An unexpected server error.
502	upstream_error	Yes	The call failed at the processing stage.
502	bad_model_output	No	The model returned an unusable result.
503	model_unavailable	Yes	No GPU node is serving the model right now. During a short loss of contact with the only worker (about a minute), only interactive calls get this error, with Retry-After: 5; sync and batch calls wait in the queue until their deadline.
503	model_busy	Yes	The queue of the model is full or the expected wait is too long.
503	unavailable	Yes	A temporary shortage, for example while image processing is busy or image storage is unavailable.
504	upstream_timeout	Yes	The call passed its deadline.

The constraints that produce 400 invalid_request are listed per field in the API reference.

daily_limit_reached carries Retry-After until the next UTC day, but repeating the same request before then fails again. Add credit to unlock higher limits. See Rate limits and pools.

Retry guidance

• Repeat a call only when retryable is true.
• Wait at least retryAfterMs (or Retry-After seconds) before the next attempt. For model_unavailable and model_busy without a hint, the server suggests 5000 ms.
• Send an Idempotency-Key on calls that spend credits, so that a repeated call cannot be charged or run twice.
• On 404 image_not_found, upload the image again; the call can then be repeated.
• Other 4xx errors need a change to the request or the account before another attempt.

Request id

Every response, errors included, carries an X-Request-Id header: 16 random hexadecimal characters generated by the server. A value sent by the client is ignored. Successful inference responses also carry a call id in the id field (call_<uuid>). Quote either value when contacting support.

Idempotency

Send Idempotency-Key: <1 to 128 printable ASCII characters> on any POST that spends credits.

• Within an account, a key is remembered for 24 hours.
• Repeating a request with the same key and the same body returns the original response, status and body, with the header Idempotent-Replayed: true. The call is not charged and not run again.
• The same key with a different body is 409 idempotency_conflict.
• The same key while the first request is still running is 409 request_in_progress.
• Only final outcomes are stored: 2xx and permanent 4xx. A 402, 429 or 5xx frees the key, so the same request can be retried under it.

curl https://api.stack.foldbun.com/v1/ocr \
  -H "Authorization: Bearer $FOLDBUN_API_KEY" \
  -H "Idempotency-Key: 6d1a8b3e-1f6e-4f0c-9d54-2b8f7c1e0a11" \
  -H "Content-Type: application/json" \
  -d '{"image": {"id": "img_2dedd0716bfd46ec29b286a279d18b6fc80631e5d90fedb5c63eb36f231622e6"}}'