Handle API errors
Use the HTTP status for the broad outcome, errorType for the specific cause, and recovery for the next action. Every REST response includes X-Request-Id.
Correct input or account state
| Status and errorType | Recovery |
|---|---|
400 INVALID_JSON / VALIDATION_ERROR | Correct JSON or the fields listed in details. Unchanged input should not be retried. |
401 AUTHENTICATION_REQUIRED / NEED_API_KEY | Provide a subscription-backed API key. NEED_API_KEY is a REST compatibility value. |
401 AUTHORIZATION_HEADER_INVALID | Correct the Bearer header format. |
401 API_KEY_INVALID_OR_REVOKED / API_KEY_INVALID_CREDENTIAL | Replace the unusable key in the requesting client. |
401 ACCOUNT_SESSION_REFRESH_REQUIRED | Sign in to VidMage once; keep the client key configuration. |
402 NEED_PURCHASE_CREDITS | Add credits or lower the operation cost. |
403 NEED_SUBSCRIBE | Activate or renew the subscription. |
404 CAPABILITY_NOT_ENABLED | Refresh capability discovery and choose an enabled capability. |
410 UPLOAD_EXPIRED | Create and complete a new temporary upload. |
Wait while preserving the original request
| Status and errorType | Recovery |
|---|---|
409 UPLOAD_NOT_READY | Complete the file transfer before using its URL. |
409 IDEMPOTENCY_IN_PROGRESS | Wait for the indicated delay and retain the same idempotency value. |
409 IDEMPOTENCY_CONFLICT | Check the original request identity. Use a new key only for a genuinely different generation request. |
429 RATE_LIMITED | Honor Retry-After, then use capped backoff. Continue tracking tasks already submitted. |
TASK_QUERY_INTERRUPTED / RESULT_MISSING in MCP | Keep querying the existing task ID. |
TASK_NOT_FOUND | Check recent tasks before considering a retry. |
Resolve unknown outcomes before retrying
SUBMISSION_OUTCOME_UNKNOWN, BILLING_OUTCOME_UNKNOWN, and REFUND_OUTCOME_UNKNOWN need recovery, not an automatic new submission. Follow the response action:
| Recovery action | What to do |
|---|---|
GET_RECENT_TASKS | Use get_recent_tasks in MCP, or the REST recent-tasks endpoint. |
QUERY_TASK_ID_OR_CONTACT_SUPPORT | Query the same task ID, or contact support if it remains unresolved. |
CONTACT_SUPPORT_WITH_IDEMPOTENCY_KEY_AND_BUSINESS_ID | Retain and share the requested identifiers with support. |
Keep the original idempotency value. Do not resubmit the task or attempt a second refund while the outcome is uncertain.
Handle service errors by their cause
| Error | Recovery |
|---|---|
CREDENTIAL_STORAGE_UNAVAILABLE | Honor Retry-After and retry once. If it persists, stop and provide the request ID to support. Keep the API key and do not submit the task again. |
TASK_PERSISTENCE_UNCERTAIN | Retain taskId, avoid resubmission, and contact support if it persists. |
BILLING_INVARIANT_FAILED | Do not retry, rotate the key, change the original Idempotency-Key, or submit again. Contact support. |
Other *_SERVICE_UNAVAILABLE / UPSTREAM_* responses | Use capped backoff and retain task identity, unless a more specific recovery action applies. |
Include identifiers, exclude credentials
For support, collect X-Request-Id, capability, HTTP status, errorType, and the operation identifier, usually taskId and requestId for the two direct-media watermark-removal capabilities. Include the original idempotency key or business ID when requested. Do not include the API credential.
The authentication guide explains credential recovery, while billing behavior covers pending charges and refunds.