MAKEUGC PLATFORM API · DOCS V2

Errors & retries

Handle API errors, distinguish failed requests from failed jobs, and retry without creating duplicate generations.

Error formats

Most feature errors return a boolean status and a message. Schema validation may also return an errors array with field paths.

Feature validation error

{
  "status": false,
  "message": "Invalid request data",
  "errors": [
    {
      "path": [
        "prompt"
      ],
      "message": "Prompt is required",
      "code": "custom"
    }
  ]
}

Enterprise route errors generally return detail. Authentication and uncaught errors can still use the shared status/message structure.

Enterprise validation error

{
  "detail": "Unsupported enterprise model"
}

Read detail or message for HTTP errors. A failed job returned with HTTP 200 instead uses its job state and may include reason or error.

HTTP status codes

Code	Meaning and action
400	Invalid input, unsupported model or, on some features, insufficient credits. Correct the request or balance before resubmitting.
401	Missing, invalid or inactive API key. Check X-Api-Key.
402	Insufficient credits on endpoints that use this code. Seedance preflight errors can include data.required_credits.
403	Subscription, feature or generation access denied.
404	Resource missing, deleted or inaccessible. Check the identifier and account. Some feature routes also use 404 for a missing subscription.
422	The generation service rejected the input. Review the returned explanation.
429	Generation or request limit reached. Reduce concurrency and respect Retry-After when returned.
500	Server-side failure. Save the request ID and avoid blindly repeating a generation.
502 / 504	Upstream failure or timeout. The submission outcome may be unknown.
503	Temporary unavailability, maintenance, or an unavailable model. Sora requests are currently rejected.

Not every endpoint uses every code. For example, Content Library generation can wrap an upstream rejection as 502; read the body for context.

Retry safely

Retry transient GET failures with a bounded timeout and exponential backoff. Respect Retry-After when present.
There is no documented idempotency-key contract for generation. Repeating a POST may create another billable job.
After a submission timeout, preserve any received job ID and check your dashboard or contact support before sending another generation request.
Do not repeatedly retry validation, authentication, access or insufficient-credit errors.
Unknown job states should be logged and investigated; avoid an unbounded loop.

Contact support

Send the request method and path, HTTP status, x-request-id , generation job ID (if available), approximate time and a redacted request body to help@makeugc.ai. Never include your API key.