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
401	`UNAUTHORIZED`	Missing, invalid, or revoked API key	No — check the key
402	`INSUFFICIENT_CREDITS`	Balance too low for this call	After topping up
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 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
401	`UNAUTHORIZED`	Missing, invalid, or revoked API key	No — check the key
402	`INSUFFICIENT_CREDITS`	Balance too low for this call	After topping up
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 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.