Errors

Every error is application/problem+json with a stable code and a sentence that says what to do.

HTTP/1.1 402 Payment Required
Content-Type: application/problem+json

{
  "type": "https://trycutstack.com/docs/errors#NO_CREDITS",
  "title": "Not enough credits",
  "status": 402,
  "code": "NO_CREDITS",
  "detail": "You don’t have enough credits for this batch. Add credits and try again.",
  "needed": 120,
  "balance": 35
}

Branch on code, never on detail (the sentence may change). Extra members depend on the code: errors for validation, needed and balance for credits, retryAfter for rate limits, jobId, itemId and reason on the single-image endpoint.

Codes

Code	Status	When	What to do
`VALIDATION`	400	A field is missing or out of range. `errors` lists each issue with its path.	Fix the request. Nothing happened.
`UNAUTHENTICATED`	401	No `Authorization: Bearer` header.	Send your key.
`INVALID_KEY`	401	The key is malformed, unknown or revoked.	Create a new key in the studio; the old one is dead.
`NO_CREDITS`	402	Starting, continuing or retrying needs more credits than you have. `needed`, `balance`.	Buy credits in the studio, then retry the same call. The batch is untouched.
`SESSION_REQUIRED`	403	A key called something only a signed-in session may do (keys, purchases, account deletion).	Do it in the studio.
`NOT_FOUND`	404	No batch or photo with that id on this account.	Check the id; batches are deleted two hours after they finish.
`NOT_DRAFT`	409	Adding photos or starting a batch that was already started.	Create a new batch.
`NOT_RUNNING`	409	Stopping a batch that is not running.	Nothing to do.
`TOO_MANY_ACTIVE`	409	The account already has the maximum number of batches running (two).	Wait for one to finish (`?wait=`), or stop it.
`IN_PROGRESS`	409	The same `Idempotency-Key` is still being processed.	Wait for that answer; do not send a third request.
`CONFLICT`	409	The action does not fit the state: nothing to retry, no finished photos to download, a photo still processing, a report on a refunded photo (`reason`).	Read `detail`.
`PROCESSING_FAILED`	422 / 503	`POST /v1/images` only: the photo failed. 422 when the input is at fault (`reason`: INVALID_IMAGE, NO_SUBJECT, …), 503 when the model was unavailable.	Nothing charged. Fix the file, or retry later.
`RATE_LIMITED`	429	Over 60 requests/min or 2,000 photos/hour for this key. `retryAfter`, `Retry-After`.	Back off for `retryAfter` seconds.
`UPLOAD_FAILED`	500	Storing the photos failed on our side.	Retry the same request.
`SERVICE_UNAVAILABLE`	503	The model is not reachable right now.	Retry in a few minutes. Nothing was charged.
`TIMEOUT`	504	`POST /v1/images` only: the photo never started within `timeout`.	The reservation was released. Retry, or use a batch.
`STORAGE_FULL`	507	Our data volume is full.	Retry later; we are alerted.
`KEY_LIMIT`	409	Ten active keys already (studio only).	Revoke one.

Failures on photos

A photo that fails inside a batch is not an HTTP error: the batch answers normally and the photo carries status: "failed" with an error object. Its code is one of INVALID_IMAGE, TOO_LARGE, NO_SUBJECT, REMOTE_BAD_INPUT (the input), REMOTE_UNAVAILABLE, REMOTE_RATE_LIMIT, PROCESSING_FAILED (our side, worth a retry), CANCELLED. Failed photos are never charged and are listed in the review queue.

Retrying safely

Idempotent by nature: every GET, DELETE, /apply, /cancel.
Idempotent with the header: /start and /v1/images. Always send Idempotency-Key; on a network error, resend the same request with the same key.
Not idempotent: /items (resending adds the photos again; they are cheap to remove and nothing is charged in a draft), /continue and /retry (a second call after success answers 409, so it is safe to resend once).
5xx and 429 are worth an automatic retry with backoff; 4xx are not.

Error messages never name the model or the infrastructure behind it. If you see a message you cannot act on, write to us with the batch id.

Next: Limits and rules. Sizes, rates, the two-hour rule, formats.