Errors

MoonNexAI returns a consistent error object to help you diagnose failures, correct requests and decide whether to retry.

Response format

{
  "error": {
    "message": "Invalid API key.",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}

Common Errors

HTTP status code	type	code	Annotations
400	invalid_request_error	invalid_request	request body is formatted wrong, field or field type is missing correctly.
400	invalid_request_error	invalid_parameter	Parameter values are not within the scope of the model support, e.g. size, duration, aspect ratio or quantity are not valid.
401	authentication_error	missing_api_key	The request is missing the Authorization header.
401	authentication_error	invalid_api_key	API Key does not exist, is invalid or is formatted wrong.
403	permission_error	model_not_enabled	Currently account does not have a model or capability for the request facility.
404	not_found_error	task_not_found	task does not exist or does not belong to the current account.
409	task_error	task_canceled	task has been cancelled and cannot continue searching for results or retry the current task.
422	content_policy_error	asset_rejected	Uploading media assets or generating content does not comply with Platform security rules.
429	rate_limit_error	rate_limit_exceeded	The request rate exceeds the account or model limit.
402	billing_error	insufficient_balance	account balance or insufficient amount.
500	server_error	service_error	MoonNexAI service anomaly, please try again later.
502	service_error	model_service_unavailable	Model services are not available for the time being, but please try again later.
504	timeout_error	request_timeout	request or task await timeout.

Recommended handling

• 400, 422: Check request parameters and media assets for resubmission.
• 401: Checks the API Key for correctness and confirms that the placeholder is not used as a real key.
• 402, 403: Check balance, amount and model privileges at MoonNexAI console.
• 429: Reduce concurrency and increase the delay between retries.
• 5xx: Retry with exponential backoff and retain task_id for troubleshooting.