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.

Calls to /v1 carry a typed error object as well. Branch on error.type and error.code rather than on the message text, which is written for people and may be reworded.

401 — invalid key
{
  "success": false,
  "message": "That API key is invalid or has been revoked.",
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "That API key is invalid or has been revoked.",
    "docs": "https://imagemcpserver.com/docs/errors"
  }
}
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 revoked. A revoked key is a 401 on /v1 — never a 403.No — fix credentials
429Rate limitedToo many requests for this key inside the window. Retry-After says how many seconds to wait.Yes — after Retry-After
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.
  • On 429, wait the number of seconds in Retry-After before the next attempt.
  • 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 /v1/me is the cheapest way to test a key on its own.