Skip to main content
All errors share one envelope: 
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_request",
    "message": "image must be an https URL or a data:image/* URI",
    "param": "image"
  }
}
FieldDescription
typeHigh-level category — one of the values in the table below.
codeMachine-readable specific reason (e.g. subscription_required, invalid_image_url).
messageHuman-readable explanation. Do not parse.
paramWhen the error is about a request field, the JSON path of the offending field.

​
Status codes

StatustypeMeaning
400invalid_request_errorMalformed body or invalid field (param points at it).
401authentication_errorMissing, invalid, or expired API key.
403authorization_errorKey disabled, missing metadata, or no active subscription.
404not_found_errorResource does not exist.
409conflict_errorConflicting request (e.g. duplicate webhook URL).
429rate_limit_errorToo many requests — see Rate limits.
500api_errorUnexpected server error. Retry with backoff.

​
Handling errors

  • 400 invalid_request_error — your bug. Inspect param and fix the request. Do not retry without changes.
  • 401 / 403 — credential or subscription issue. Don’t retry; surface to the operator.
  • 404 — usually a stale ID. Don’t retry.
  • 409 — fix the conflict (e.g. choose a different URL) and retry.
  • 429 — back off exponentially and retry.
  • 500 — server-side. Retry with exponential backoff.