Get API key
Guides

Errors & troubleshooting

Every failure the API returns, what it means, and whether retrying will help — including the credit rules that decide whether a failed call costs you anything.

Error shape

Failures use the same envelope as successes, with success: false and a human-readable message. Some errors add fields that tell you exactly what to do next.

400 — insufficient credits
{
  "success": false,
  "message": "Insufficient credits. You need 15 credits, but only have 4 credits available.",
  "currentCredits": 4,
  "requiredCredits": 15
}
400 — prompt rejected
{
  "success": false,
  "isNsfw": true,
  "message": "NSFW Content Detected: …",
  "reason": "…",
  "category": "…"
}

Status codes

StatusMeaningRetry?
400Bad requestA required parameter is missing, or the request was rejected before it reached a model.No — fix the request
400Insufficient creditsValid key, empty balance. The body includes currentCredits and requiredCredits.No — top up
400Prompt rejectedThe prompt failed the safety screen. The body includes isNsfw, reason and category.No — rewrite the prompt
401UnauthorizedNo key, an invalid key, or a key that has been deleted.No — fix credentials
403ForbiddenThe session or token is no longer valid for this account.No — sign in again
404Not foundThe account behind the key no longer exists.No
500Provider or server errorThe upstream model failed, timed out, or returned nothing usable. message carries the detail.Yes — once or twice

Common failures

  • Prompt is required — generation was called with an empty prompt. Only remove_bg and upscale actions supply their own.
  • Input image is required — edit, remove_background, upscale, compress and convert_format all need image (or imageBase64).
  • requests array is required — multicall was called without a non-empty array.
  • A reference image URL that the server cannot fetch — use a publicly reachable https URL, or send the bytes as a base64 data URI.
  • Tools missing in an MCP client — the client was not restarted, or the config JSON failed to parse.

Errors and credits

The order of operations matters. The balance is checked and credits are deducted before the request goes to a model, so an error raised at validation time costs nothing — but a failure after that point has already been charged.

  • Rejected for a missing parameter, a bad key, or an insufficient balance → no credits taken.
  • Rejected by the safety screen → no credits taken; the screen runs before the deduction.
  • Deducted, then the model failed → credits already spent, and not returned automatically.

Do not loop on failures

Because failed generations are not auto-refunded, an agent that retries a persistent error will drain the balance. Cap retries, and surface the message to the user instead.

Retry strategy

  • Retry 500 responses at most twice, with a short backoff.
  • Never retry 400 or 401 — the request or the key has to change first.
  • In a multicall, retry only the items whose success is false; the rest already succeeded.
  • Read userCredits from the last successful response before retrying, so you know what is left to spend.

FAQ

Should my agent retry a failed generation?

Only for 5xx failures, and at most once or twice with backoff. Credits are deducted before the model runs, so a retry loop on a persistent failure spends the balance without producing an image.

Why did I get a 400 saying my prompt violates safety policies?

Prompts are screened before generation. The response includes isNsfw: true along with a reason and category. Rewrite the prompt rather than retrying it unchanged.

My call returned 401 but my key is correct.

Check the header is reaching the server intact — a stray space after "Bearer", a truncated copy-paste, or a deleted key are the usual causes. GET /auth/user-data is the cheapest way to test a key on its own.