Error Codes

All PhantomFlow API errors return a JSON body with an error object containing a machine-readable code and a human-readable message.

Error response format

{
  "error": {
    "code": "SCHEMA_VALIDATION_ERROR",
    "message": "Expected number, received string",
    "path": "scenes.0.duration"
  }
}

The path field is included for validation errors to identify the failing field. The required and balance fields are included for insufficient credits errors.

All error codes

HTTP	Code	Description	Resolution
`400`	`INVALID_JSON`	Request body is not valid JSON.	Ensure your request body is valid JSON.
`400`	`SCHEMA_VALIDATION_ERROR`	The movie script does not match the expected schema. The response includes the failing path.	Check the error path field and validate against GET /api/render/schema.
`400`	`VALIDATION_ERROR`	A request field failed validation (e.g., empty template name).	Check the error message for the specific field that failed.
`400`	`INVALID_REQUEST`	Required field missing or invalid (e.g., missing template_id).	Review the endpoint documentation for required fields.
`401`	`UNAUTHORIZED`	The x-api-key header is missing, invalid, or revoked.	Check that you are passing a valid API key in the x-api-key header.
`402`	`INSUFFICIENT_CREDITS`	Your account does not have enough credits for the estimated render cost.	Top up your credit balance in the billing dashboard.
`403`	`FORBIDDEN`	You do not have permission to access this resource (e.g., another user's template).	Check that you own the resource or that it is public.
`404`	`NOT_FOUND`	The requested resource (job, template) was not found.	Verify the resource ID. Jobs and templates return 404 for non-existent or non-owned resources.
`404`	`TEMPLATE_NOT_FOUND`	The template_id in a render request does not exist.	Verify the template ID with GET /api/templates.
`429`	`RATE_LIMIT_EXCEEDED`	Too many API requests in a given time window.	Wait for the duration specified in the Retry-After response header before retrying.
`429`	`CONCURRENCY_LIMIT_EXCEEDED`	Too many render jobs are currently running for your account.	Wait for active jobs to complete before submitting new ones.
`500`	`INTERNAL_ERROR`	An unexpected server error occurred.	Retry with exponential backoff. Contact support if persistent.
`500`	`RENDER_FAILED`	The video render process failed (FFmpeg error, invalid source, etc.).	Check the error message for details. Verify source URLs are accessible and media formats are supported.

Rate Limits

Rate limits are enforced per account. When you exceed the limit, the API returns a 429 status with a Retry-After header indicating how many seconds to wait.

Plan	Requests / minute	Concurrent Jobs
Free	10	2
Starter	60	5
Pro	120	10
Enterprise	Custom	Custom

Rate limit response headers

Every API response includes rate limit information in the headers:

Header	Description
`X-RateLimit-Limit`	Maximum requests per window
`X-RateLimit-Remaining`	Remaining requests in the current window
`X-RateLimit-Reset`	Unix timestamp when the current window resets
`Retry-After`	Seconds to wait before retrying (only on 429 responses)

Troubleshooting Tips

SCHEMA_VALIDATION_ERROR: Fetch the JSON Schema via GET /api/render/schema and validate your payload locally before submitting.
INSUFFICIENT_CREDITS: The estimated cost is deducted upfront. If the actual cost is lower, the difference is refunded automatically.
RENDER_FAILED: Check that all media URLs (src fields) are publicly accessible and return valid media files. Common issues include expired pre-signed URLs and incorrect MIME types.
RATE_LIMIT_EXCEEDED: Implement exponential backoff in your client. Both official SDKs handle this automatically for server errors.
Sandbox mode: Use a ve_test_ key to test your integration without consuming credits. Sandbox returns mock responses.

PreviousWebhooks