Errors and retries
Diagnose failed requests and retry only when the error can recover.
When a request fails, inspect its HTTP status and errorCode. A status alone is not enough to choose a recovery action: a 429 can mean temporary throttling or an exhausted API-key usage limit.
Error response
HTTP errors use these problem fields:
| Field | Meaning |
|---|---|
type | Error category. |
title | Short summary. |
status | HTTP status. |
detail | Explanation for the caller. |
errorCode | Business error code, when available. Use it for recovery logic. |
Keep the code and relevant request context in your server logs. Do not log API keys. Show users a message that explains what they can change, rather than displaying a raw response or stack trace.
Choose an action
| Error | Action |
|---|---|
401 | Check or replace the API key. Do not retry unchanged credentials. |
403 or an access error | Confirm workspace membership, resource access, and permission for the action. |
404 | Check the resource ID and the key's workspace. |
Invalid state or 400 / 422 input error | Correct the request, then validate and submit again. |
OPEN_API_PROJECT_SYNC_RATE_LIMITED | Reduce autosave frequency and retry with backoff. |
OPEN_API_EXPORT_CONCURRENCY_LIMIT_EXCEEDED | Wait for another workspace export to finish before submitting. |
OPEN_API_EXPORT_STANDARD_SECOND_LIMIT_EXCEEDED | Review the API key's usage limit. Waiting alone does not restore this limit. |
OPEN_API_EXPORT_RESOLUTION_FORBIDDEN | Choose a permitted output resolution or change the workspace plan. |
OPEN_API_EXPORT_FPS_FORBIDDEN | Choose a permitted frame rate or change the workspace plan. |
ASSET_REFERENCED | Remove references before deleting the asset. |
409 during cancellation | Fetch the task's latest state; it may already have finished. |
| Insufficient credits | Add credits to the workspace or reduce the requested work. |
For an unrecognized code, preserve the response for diagnosis and avoid an unbounded retry loop. Read the endpoint's response schema for its documented statuses.
Retry temporary failures
Use bounded exponential backoff with jitter for temporary throttling and transient server or network failures. Honor Retry-After when it is returned. Stop after a reasonable number of attempts and surface the failure to the caller.
A timeout does not prove that a create request failed. The server may already have accepted it. For create retries, reuse a stable Idempotency-Key and the unchanged request body; see Exports. Do not automatically retry every 429 or resubmit billable work with a new key.
Validation results and task failures
POST /v1/editor/validate can return a successful HTTP response with valid: false. Inspect errors[] and fix the state; a 200 response does not mean the video is valid.
A task can fail after its create request succeeds. Read status and error from the task snapshot. SDK wait helpers raise an error for FAILED or CANCELED; stopping a wait does not cancel the server task.
SDK exceptions
JavaScript and Python expose AuthError, ValidationError, RateLimitError, and APIError. Inspect the underlying problem's business code before applying a retry policy, including when the exception is a RateLimitError.
Last updated on