Docs · v1

Errors

Platform API errors use HTTP status codes plus a JSON body. Async generation jobs can also fail after a 200 — poll status and read data.status.

HTTP status codes

Parameters

Code	When it happens
200	Request accepted. For generate jobs, poll status until completed or failed.
400	Missing fields, invalid input, file too large, or insufficient credits.
401	Missing or invalid `X-Api-Key`.
404	Avatar, voice, video, template, or subscription not found.
500	Server error. Retry with backoff, then contact help@makeugc.ai if it persists.

Authentication error

401 response

JSON json

{
  "status": false,
  "message": "Not authenticated"
}

Validation error

400 response

JSON json

{
  "status": false,
  "message": "Missing required fields or invalid input"
}

Missing resource

404 response

JSON json

{
  "status": false,
  "message": "Avatar or voice not found"
}

Failed async job

Product-in-Hand and Content Library status endpoints keep HTTP 200 and report failure on the job payload.

Failed status response

JSON json

{
  "status": true,
  "message": "Video is failed",
  "data": {
    "status": "failed",
    "reason": "Request timeout due to high load"
  }
}

Questions

What does HTTP 401 mean?

The request is not authenticated. Confirm the X-Api-Key header, that the key is active, and that the account still has API access.

How should I handle 400 vs 404?

400 means the payload is missing required fields or failed validation (script length, file type, unreachable voice_url). 404 means the referenced avatar, voice, video, or subscription was not found.

Is a failed video generation always an HTTP error?

No. Generate endpoints usually return 200 with a job id. Poll the status endpoint: data.status can be processing, completed, or failed. A failed job includes a reason field while HTTP status remains 200.