Tổng quan

Mã lỗi

Định dạng lỗi

Mọi lượt gọi lỗi — sai key, thiếu trường, sai đường dẫn — đều trả JSON theo đúng khuôn này:

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"
}

Code theo errorCode — đừng theo câu lỗi, cũng đừng theo mã HTTP (vài mã có endpoint trả HTTP khác). Ý nghĩa từng trường: Quy ước API.

Mã trạng thái HTTP

Mã	Ý nghĩa	Cách xử lý
200 / 201	Thành công	Đọc trường data
400	Request không hợp lệ	Sửa trường mà error nêu rồi gửi lại
401	Thiếu key hoặc sai key	Gửi key đúng trong header X-Api-Key
402	Không đủ credit	Nạp thêm rồi thử lại — thử lại trước đó vẫn lỗi như cũ
403	Không có quyền	Key này không dùng được endpoint này
404	Không tìm thấy	Kiểm tra đường dẫn và id
409	Đã làm rồi	Việc này đã được làm (xác nhận một file hai lần) — đừng gửi lại
422	Dữ liệu sai giá trị (tạo ảnh)	Xem errorCode, sửa giá trị rồi gửi lại
429	Gọi quá nhanh	Đợi rồi thử lại, giãn dần khoảng chờ
500 / 502 / 503	Lỗi máy chủ	Thử lại sau vài giây; vẫn lỗi thì liên hệ hỗ trợ

Đa số endpoint báo request sai bằng 400. Riêng tạo ảnh (POST /images/generations) trả 422 — thiếu model hoặc prompt, aspectRatio, format, resolution hay dpi không hợp lệ, hoặc link ảnh tham chiếu không tồn tại.

Danh sách mã lỗi

Danh sách đầy đủ, đọc từ GET /v2/errors (không cần key). Câu lỗi để tiếng Anh, đúng như khi gọi bằng API key; {tên} được điền từ details[].params. Cột HTTP là mã thường gặp — endpoint nào trả mã khác thì ghi ở trang của endpoint đó.

Mã endpoint nào cũng có thể trả:

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

Mã của từng nhóm endpoint:

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

Webhook:

errorCode	HTTP	Câu lỗi	Thử lại?
INVALID_WEBHOOK_URL	422	url must be a public https URL on port 443 without credentials.	Không
INVALID_WEBHOOK_EVENT	422	Unknown event type. See details for allowed values.	Không
WEBHOOK_LIMIT_REACHED	422	You can have at most {limit} webhook endpoints.	Không
WEBHOOK_NOT_FOUND	404	Webhook endpoint not found.	Không
DELIVERY_NOT_FOUND	404	Delivery not found.	Không
WEBHOOK_DISABLED	409	This webhook endpoint is disabled. Enable it first.	Không

Motion — phân tích video nguồn (POST /motion/analyses; bốn mã cuối thường nằm ở error.code của lượt phân tích hỏng):

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

Trang trướcQuy ước API Trang sauThông tin tài khoản