Overview

Error codes

Error format

Every failed call — a wrong key, a missing field, a route that does not exist — answers in JSON, in this shape:

json

{
  "success": false,
  "errorCode": "INVALID_DPI",
  "error": "dpi must be between 1 and 1200.",
  "details": [
    {
      "field": "dpi",
      "code": "INVALID_DPI",
      "message": "dpi must be between 1 and 1200.",
      "params": { "min": 1, "max": 1200 }
    }
  ],
  "requestId": "4bf92f3577b34da6a3ce929d0e0e4736"
}

Branch on errorCode — not on the message, nor on the HTTP status (a few codes come with another status on some endpoints). What each field means: API conventions.

HTTP status codes

Status	Meaning	What to do
200 / 201	Success	Read the data field
400	Invalid request	Fix the field the error names, then send again
401	No key, or a wrong one	Send a valid key in the X-Api-Key header
402	Not enough credits	Top up, then retry — retrying before that fails the same way
403	Not allowed	The key cannot use this endpoint
404	Not found	Check the path and the id
409	Already done	The thing was already done (an upload confirmed twice) — do not send it again
422	A field has a wrong value (creating an image)	See errorCode, fix the value, then send again
429	Too many requests	Wait, then retry with backoff
500 / 502 / 503	Server error	Retry after a few seconds; contact support if it keeps happening

Most endpoints answer a bad request with 400. Creating an image (POST /images/generations) answers 422 instead — a missing model or prompt, an aspectRatio, format, resolution or dpi it does not take, or a reference image link that does not exist.

Error codes

The full list, read from GET /v2/errors (no key needed). Messages are in English, as calls with an API key get them; {name} is filled in from details[].params. HTTP is the usual status — an endpoint that answers another one says so on its page.

Codes any endpoint can answer:

errorCode	HTTP	Message	Retry?
BAD_REQUEST	400	The request is invalid.	No
VALIDATION_ERROR	400 (some endpoints 422)	The request contains invalid fields. See details.	No
BODY_REQUIRED	400	Request body is required.	No
UNAUTHORIZED	401	Missing or invalid API key.	No
FORBIDDEN	403	You do not have permission to do this.	No
NOT_FOUND	404	The requested resource was not found.	No
CONFLICT	409	The request conflicts with the current state of the resource.	No
PAYLOAD_TOO_LARGE	413	The request body is too large.	No
INSUFFICIENT_CREDITS	402	Not enough credits. Required: {required}, available: {available}.	No
RATE_LIMITED	429	Too many requests. Retry after {retryAfter} seconds.	Yes
TOO_MANY_ACTIVE_JOBS	429	Too many active jobs ({active}/{limit}). Wait for current jobs to finish.	Yes
INTERNAL_ERROR	500	Something went wrong on our side. Please try again.	Yes
UPSTREAM_ERROR	502	A downstream service failed. Please try again.	Yes
SERVICE_UNAVAILABLE	503	Service temporarily unavailable. Please try again later.	Yes

Codes of particular endpoints:

errorCode	HTTP	Message	Retry?
ENDPOINT_NOT_FOUND	404	Endpoint not found. Check the path and HTTP method.	No
MODEL_REQUIRED	422	model is required.	No
PROMPT_REQUIRED	422	prompt is required.	No
MODEL_NOT_FOUND	404	Model not found. See GET /v2/models for available models.	No
MODEL_WRONG_CATEGORY	422	This model belongs to another category. Use the endpoint for its category.	No
SERVER_NOT_FOUND	422	This server is not available for the model. See details for available servers.	No
IDEMPOTENCY_KEY_REUSED	422	This idempotency key was already used for a different request. Use a new key.	No
INVALID_DPI	422	dpi must be between {min} and {max}.	No
INVALID_FORMAT	422	format must be one of: {allowed}.	No
INVALID_ASPECT_RATIO	422	aspectRatio must be W:H (positive integers, e.g. 16:9) or "auto", at most {max}:1. Received "{value}".	No
INVALID_RESOLUTION	422	resolution '{value}' is not valid. Use one of: {supported}.	No
RESOLUTION_NOT_SUPPORTED	422	Resolution '{value}' is not supported yet. Available: {supported}.	No
REFERENCE_IMAGE_UNREACHABLE	422 (some endpoints 400)	Could not download reference image: {url}. Check that the link is alive and allows server downloads.	No
AGENT_QUEUE_FULL	429	The queue is full ({queued} waiting, {running} running). Try again shortly.	Yes
NO_AGENT_AVAILABLE	503	No worker is available right now. Please try again shortly.	Yes
INVALID_COUNT	422	count must be between {min} and {max}.	No
COUNT_NOT_SUPPORTED_FOR_API_KEY	400	count is web-only. With an API key, send one request per image.	No
ROUND_NOT_AFFORDABLE	402	Not enough credits for this many images.	No
INVALID_VISIBILITY	422	visibility must be 'public' or 'private'.	No
RESOLUTION_REQUIRES_PLAN	403	This resolution requires an active plan.	No
JOB_NOT_FOUND	404	Job not found.	No
JOB_NOT_READY	400	The job has not finished yet.	No
JOB_PUBLISHED	409	The job is published. Unpublish it first.	No
CHARACTER_NOT_FOUND	404	Character not found.	No
REF_IMAGE_NOT_FOUND	404	Reference image not found.	No
ASSET_NOT_FOUND	404	Asset not found.	No
ASSET_ALREADY_CONFIRMED	409	This upload was already confirmed.	No
UNSUPPORTED_FILE_TYPE	400	Unsupported file type.	No
UPLOAD_FAILED	400 (some endpoints 500)	Upload failed. Please try again.	Yes
QUOTA_EXCEEDED	429 (some endpoints 400)	Quota exceeded. Delete some items or upgrade your plan.	No
UPLOAD_QUOTA_EXCEEDED	429	Daily upload limit reached. Try again after 00:00 UTC, or use an image URL you already host.	Yes
TEAM_NOT_FOUND	404	Publishing team not found.	No
POST_NOT_FOUND	404	Post not found.	No
PUBLISH_FAILED	502	Could not publish. Please try again.	Yes
NO_API_ACCESS	403	Your plan does not include API access.	No
NO_PUBLISHING_TEAM	404	No publishing team found. Connect a social account first.	No
INVALID_GENRE	422	Unknown music genre.	No
NO_CONNECTED_ACCOUNT	400	This platform is not connected. Connect it first.	No
ACCOUNT_NEEDS_ATTENTION	409	The page for {platform} changed or lost access. Select the page again before posting.	No
CHANNEL_LIMIT	403	Connected channel limit reached.	No
NO_SUBSCRIPTION	500	Publishing is not set up for this account. Contact support.	No
INVALID_DATE_RANGE	400	Invalid date range. Use 1DAY, 7DAY or 30DAY.	No
BRAND_KIT_NOT_FOUND	404	Brand kit not found, or it belongs to another account.	No
STYLE_NOT_FOUND	404	Saved style not found, or it belongs to another account.	No
PROPS_INVALID	400	A request field is invalid. The error message says which one.	No
PROP_INVALID	400	Field {field} {reason}.	No
PROP_TOO_LONG	400	Field {field} {reason}.	No
PROP_REQUIRED	400	Field {field} {reason}.	No
ASSET_INVALID	400	The file could not be used. The error message says why.	No
ASSET_MISSING	404	The referenced asset was not found.	No
ASSET_KIND_NOT_ALLOWED	400	This kind of asset is not allowed here.	No
AUDIO_SOURCE_CONFLICT	400	Send only one of audioKey or audioUrl.	No
ROTATE_REQUIRES_LOGIN	403	An API key cannot rotate itself. Sign in to rotate it.	No

Webhooks:

errorCode	HTTP	Message	Retry?
INVALID_WEBHOOK_URL	422	url must be a public https URL on port 443 without credentials.	No
INVALID_WEBHOOK_EVENT	422	Unknown event type. See details for allowed values.	No
WEBHOOK_LIMIT_REACHED	422	You can have at most {limit} webhook endpoints.	No
WEBHOOK_NOT_FOUND	404	Webhook endpoint not found.	No
DELIVERY_NOT_FOUND	404	Delivery not found.	No
WEBHOOK_DISABLED	409	This webhook endpoint is disabled. Enable it first.	No

Motion — reading a source video (POST /motion/analyses; the last four usually come as error.code of an analysis that failed):

errorCode	HTTP	Message	Retry?
TEMPLATE_NOT_FOUND	404	Template not found, or your account has no access to it.	No
SOURCE_NOT_SUPPORTED	400	This template does not accept a source video.	No
URL_NOT_ALLOWED	400	sourceUrl must be a public http(s) URL on port 80 or 443.	No
ANALYSIS_NOT_FOUND	404	Analysis not found.	No
URL_FETCH_FAILED	502	Could not download the video from this URL.	Yes
ASSET_TOO_LARGE	413	The video is too large (max 300 MB).	No
SOURCE_INVALID	422	The source video could not be read. Use an mp4 / mov / webm file.	No
ANALYSIS_FAILED	502	Video analysis failed. Please try again later.	Yes

PreviousAPI conventions NextAccount