Errors

All errors share one envelope:

{
  "success": false,
  "error": { "code": "INSUFFICIENT_CREDITS", "message": "…" }
}

Error codes

HTTP	Code	Meaning	Retry?
400	`INVALID_INPUT`	Missing or invalid parameter; the message names the field	No — fix the request
400	`INVALID_IDEMPOTENCY_KEY`	`Idempotency-Key` is not 1–255 permitted characters	No — send a valid key or omit the optional header
401	`UNAUTHORIZED`	Missing, invalid, or revoked API key	No — check the key
402	`INSUFFICIENT_CREDITS`	Balance too low for this call	After topping up
409	`REQUEST_IN_PROGRESS`	The same idempotency key is still being processed	Yes — wait briefly, then retry the identical request with the same key
409	`IDEMPOTENCY_CONFLICT`	The key was already used for a different request	No — use a new key for the new request
422	`FETCH_FAILED`	`imageUrl` could not be fetched or returned an error	Check the URL is public
429	`RATE_LIMITED`	Over 60 requests/minute on this key	Yes — back off and retry
500	`GENERATION_FAILED`	Model or processing failure	Yes — safe to retry once
500	`INTERNAL_ERROR`	Unexpected server error	Yes — safe to retry once

Credits are only charged on success, so retrying a failed call never double-bills.
For a timeout on a paid POST, reuse the same Idempotency-Key (not a new key) for the identical request. The key is retained for 24 hours.
For 429, wait for the window to reset (up to 60 s) — an exponential backoff starting at 5 s works well.
For 500, one retry is reasonable; persistent failures usually indicate an input the model cannot process (e.g. a photo sent to a line-art pipeline). If a request keeps failing, contact contact@patentfig.ai with the request payload.

All errors share one envelope:

{
  "success": false,
  "error": { "code": "INSUFFICIENT_CREDITS", "message": "…" }
}

HTTP	Code	Meaning	Retry?
400	`INVALID_INPUT`	Missing or invalid parameter; the message names the field	No — fix the request
400	`INVALID_IDEMPOTENCY_KEY`	`Idempotency-Key` is not 1–255 permitted characters	No — send a valid key or omit the optional header
401	`UNAUTHORIZED`	Missing, invalid, or revoked API key	No — check the key
402	`INSUFFICIENT_CREDITS`	Balance too low for this call	After topping up
409	`REQUEST_IN_PROGRESS`	The same idempotency key is still being processed	Yes — wait briefly, then retry the identical request with the same key
409	`IDEMPOTENCY_CONFLICT`	The key was already used for a different request	No — use a new key for the new request
422	`FETCH_FAILED`	`imageUrl` could not be fetched or returned an error	Check the URL is public
429	`RATE_LIMITED`	Over 60 requests/minute on this key	Yes — back off and retry
500	`GENERATION_FAILED`	Model or processing failure	Yes — safe to retry once
500	`INTERNAL_ERROR`	Unexpected server error	Yes — safe to retry once

Credits are only charged on success, so retrying a failed call never double-bills.
For a timeout on a paid POST, reuse the same Idempotency-Key (not a new key) for the identical request. The key is retained for 24 hours.
For 429, wait for the window to reset (up to 60 s) — an exponential backoff starting at 5 s works well.
For 500, one retry is reasonable; persistent failures usually indicate an input the model cannot process (e.g. a photo sent to a line-art pipeline). If a request keeps failing, contact contact@patentfig.ai with the request payload.