Error Codes - Wizzx AI

The Wizzx API uses conventional HTTP response codes to indicate the success or failure of an API request. The API returns errors in an OpenAI-compatible format for easy integration with existing SDKs.

Error Response Format

All error responses follow this structure:

{
  "error": {
    "message": "Human-readable error message with solution",
    "type": "error_category",
    "param": "parameter_name",
    "code": "specific_error_code"
  },
  "request_id": "req_abc123"
}

Field	Description
`message`	A human-readable description of the error with suggested solutions
`type`	The category of error, useful for SDK exception mapping
`param`	The parameter that caused the error (null if not applicable)
`code`	A specific error code for programmatic handling
`request_id`	Unique identifier for the request, useful for support

HTTP Status Codes Overview

Status Code	Type	Description
400	`invalid_request_error`	The request was malformed or missing required parameters
401	`authentication_error`	Invalid or missing API key
402	`insufficient_quota`	Not enough credits to complete the request
403	`permission_denied`	You don’t have access to the requested resource
404	`not_found_error`	The requested resource doesn’t exist
409	`conflict_error`	The request conflicts with current state
422	`unprocessable_entity_error`	The request was well-formed but cannot be processed
429	`rate_limit_error`	Too many requests in a short period
500	`server_error`	Something went wrong on our end
503	`service_unavailable`	The service is temporarily unavailable

Authentication Errors (401)

Authentication errors occur when there’s an issue with your API key.

`missing_api_key`

{
  "error": {
    "message": "Missing API key. Include your API key in the Authorization header using Bearer authentication.",
    "type": "authentication_error",
    "param": null,
    "code": "missing_api_key"
  }
}

Solution: Add the Authorization header to your request:

curl -H "Authorization: Bearer YOUR_API_KEY" ...

`invalid_api_key`

{
  "error": {
    "message": "Invalid API key provided. Ensure the API key is correct and active.",
    "type": "authentication_error",
    "param": null,
    "code": "invalid_api_key"
  }
}

Solution: Verify your API key is correct. You can manage your API keys in the API Keys Dashboard.

`api_key_revoked`

{
  "error": {
    "message": "API key has been revoked. Generate a new API key from your dashboard.",
    "type": "authentication_error",
    "param": null,
    "code": "api_key_revoked"
  }
}

Solution: Generate a new API key from your dashboard.

Invalid Request Errors (400)

These errors indicate issues with the request format or parameters.

`missing_required_parameter`

{
  "error": {
    "message": "Missing required parameter 'prompt'. Include this parameter in your request.",
    "type": "invalid_request_error",
    "param": "prompt",
    "code": "missing_required_parameter"
  }
}

Solution: Include the required parameter in your request body.

`invalid_parameter_value`

{
  "error": {
    "message": "Invalid value for 'duration': must be one of: 5, 10. Check the API documentation for valid values.",
    "type": "invalid_request_error",
    "param": "duration",
    "code": "invalid_parameter_value"
  }
}

Solution: Check the API documentation for valid parameter values.

`invalid_json_body`

{
  "error": {
    "message": "Could not parse JSON body. Ensure your request body is valid JSON.",
    "type": "invalid_request_error",
    "param": null,
    "code": "invalid_json_body"
  }
}

Solution: Validate your JSON syntax before sending. Use a JSON validator if needed.

`model_not_supported`

{
  "error": {
    "message": "Model 'invalid-model' is not supported. Check available models in the API documentation.",
    "type": "invalid_request_error",
    "param": "model",
    "code": "model_not_supported"
  }
}

Solution: Use a supported model name. Check the pricing page for available models.

Insufficient Quota Errors (402)

These errors indicate billing or credit issues.

`insufficient_credits`

{
  "error": {
    "message": "Insufficient credits: balance is 50 credits, but this request requires 100 credits (shortfall: 50 credits). Top up at https://wizzx.ai/dashboard/billing",
    "type": "insufficient_quota",
    "param": null,
    "code": "insufficient_credits"
  },
  "balance": 50,
  "required": 100,
  "shortfall": 50,
  "billing_url": "https://wizzx.ai/dashboard/billing"
}

Solution: Add more credits to your account from Billing. Insufficient-credit rejections roll back atomically before queuing—no failed task record is created and zero credits are deducted.

`billing_not_active`

{
  "error": {
    "message": "Billing is not active on your account. Add a payment method to continue.",
    "type": "insufficient_quota",
    "param": null,
    "code": "billing_not_active"
  }
}

Solution: Activate billing by adding a payment method in your account settings.

Permission Denied Errors (403)

These errors indicate access restrictions.

`access_denied`

{
  "error": {
    "message": "You don't have permission to access this resource. Contact your administrator.",
    "type": "permission_denied",
    "param": null,
    "code": "access_denied"
  }
}

Solution: Contact your administrator or upgrade your plan.

`model_access_denied`

{
  "error": {
    "message": "You don't have access to model 'veo-3'. Upgrade your plan or contact support.",
    "type": "permission_denied",
    "param": null,
    "code": "model_access_denied"
  }
}

Solution: Upgrade your subscription plan or contact support for access.

`ip_not_allowed`

{
  "error": {
    "message": "Your IP address is not allowed. Check your API key's IP allowlist settings.",
    "type": "permission_denied",
    "param": null,
    "code": "ip_not_allowed"
  }
}

Solution: Update the IP allowlist in your API key settings.

Not Found Errors (404)

These errors indicate the requested resource doesn’t exist.

`task_not_found`

{
  "error": {
    "message": "Task 'task_abc123' not found. Ensure the task ID is correct and the task hasn't expired.",
    "type": "not_found_error",
    "param": null,
    "code": "task_not_found"
  }
}

Solution: Verify the task ID is correct. Note that task data expires after a period of time.

`model_not_found`

{
  "error": {
    "message": "Model 'unknown-model' does not exist. Check available models at /v1/models endpoint.",
    "type": "not_found_error",
    "param": null,
    "code": "model_not_found"
  }
}

Solution: Use the /v1/models endpoint to list available models.

`music_action_not_found`

{
  "error": {
    "message": "Music action 'remix' does not exist. Supported: add-instrumental, add-stem, add-vocals, adjust-speed, aligned-lyrics, bpm, concat, cover, create-model, create-voice, crop, download, extend, fade-in, fade-out, generate, inspo, lyrics, mashup, midi, music-video, persona, remaster, remove-section, replace-section, sample, sounds, stems, stems-all, upload, upload-cover, upload-extend, upsample-tags",
    "type": "not_found_error",
    "param": null,
    "code": "music_action_not_found"
  }
}

Solution: Use one of the actions listed in the message. See Submit music action.

`resource_not_found`

{
  "error": {
    "message": "The requested resource was not found. Verify the endpoint URL is correct.",
    "type": "not_found_error",
    "param": null,
    "code": "resource_not_found"
  }
}

Solution: Check that the endpoint URL is correct.

Conflict Errors (409)

These errors indicate conflicts with the current resource state.

`resource_conflict`

{
  "error": {
    "message": "A conflict occurred with resource 'api_key_123'. The resource may have been modified. Refresh and retry.",
    "type": "conflict_error",
    "param": null,
    "code": "resource_conflict"
  }
}

Solution: Refresh your local state and retry the operation.

`duplicate_resource`

{
  "error": {
    "message": "Resource 'my-api-key' already exists. Use a different identifier or update the existing resource.",
    "type": "conflict_error",
    "param": null,
    "code": "duplicate_resource"
  }
}

Solution: Use a unique identifier or update the existing resource instead.

`concurrent_update`

{
  "error": {
    "message": "The resource was modified by another request. Refresh and retry your update.",
    "type": "conflict_error",
    "param": null,
    "code": "concurrent_update"
  }
}

Solution: Fetch the latest version and retry your update.

`idempotency_key_conflict`

{
  "error": {
    "message": "Idempotency-Key was already used with a different request payload or endpoint. Generate a new Idempotency-Key for a new task.",
    "type": "conflict_error",
    "param": "Idempotency-Key",
    "code": "idempotency_key_conflict"
  }
}

Solution: Use a fresh Idempotency-Key whenever you change the submit endpoint or request JSON body.

`idempotency_key_in_progress`

{
  "error": {
    "message": "A request with this Idempotency-Key is currently being processed. Wait briefly before retrying.",
    "type": "conflict_error",
    "param": "Idempotency-Key",
    "code": "idempotency_key_in_progress"
  }
}

Solution: Wait a moment for the original submission to finish, then retry with the same Idempotency-Key to receive the cached response without double-billing.

Unprocessable Entity Errors (422)

These errors indicate the request was well-formed but cannot be processed.

`validation_failed`

{
  "error": {
    "message": "Validation failed: aspect_ratio must match the image dimensions.",
    "type": "unprocessable_entity_error",
    "param": null,
    "code": "validation_failed"
  }
}

Solution: Check the error message for specific validation requirements.

`invalid_image_url`

{
  "error": {
    "message": "Unable to process image at 'https://example.com/image.jpg'. Ensure the URL is accessible and points to a valid image.",
    "type": "unprocessable_entity_error",
    "param": "image_url",
    "code": "invalid_image_url"
  }
}

Solution: Verify the image URL is publicly accessible and returns a valid image.

`image_too_large`

{
  "error": {
    "message": "Image exceeds maximum size of 20MB. Reduce the image size and retry.",
    "type": "unprocessable_entity_error",
    "param": "image_url",
    "code": "image_too_large"
  }
}

Solution: Compress or resize your image to meet the size requirements.

`unsupported_image_format`

{
  "error": {
    "message": "Image format not supported. Use JPEG, PNG, or WebP format.",
    "type": "unprocessable_entity_error",
    "param": "image_url",
    "code": "unsupported_image_format"
  }
}

Solution: Convert your image to JPEG, PNG, or WebP format.

`content_policy_violation`

{
  "error": {
    "message": "Request blocked by content safety policy.",
    "type": "unprocessable_entity_error",
    "param": "prompt",
    "code": "content_policy_violation"
  }
}

Solution: Revise the prompt or reference inputs to comply with safety guidelines. No task is created and zero credits are deducted.

Rate Limit Errors (429)

These errors indicate you’re sending requests too quickly.

`rate_limit_exceeded`

{
  "error": {
    "message": "Rate limit exceeded. You are sending requests too quickly. Retry after 60 seconds.",
    "type": "rate_limit_error",
    "param": null,
    "code": "rate_limit_exceeded"
  },
  "retry_after": 60
}

Solution: Implement exponential backoff in your code. Both the retry_after JSON field and the standard HTTP Retry-After (plus X-Retry-After) response header indicate how many seconds to wait before retrying.

import time

def call_api_with_retry(func, max_retries=3):
    for attempt in range(max_retries):
        try:
            return func()
        except RateLimitError as e:
            if attempt < max_retries - 1:
                time.sleep(e.retry_after or 60)
            else:
                raise

`requests_quota_exceeded`

{
  "error": {
    "message": "You exceeded your request quota. Wait until your quota resets or upgrade your plan.",
    "type": "rate_limit_error",
    "param": null,
    "code": "requests_quota_exceeded"
  }
}

Solution: Wait for your quota to reset or upgrade to a higher tier.

Server Errors (500)

These errors indicate problems on our end.

`internal_error`

{
  "error": {
    "message": "The server had an error processing your request. Retry after a brief wait. If the issue persists, contact support with request_id: req_abc123",
    "type": "server_error",
    "param": null,
    "code": "internal_error"
  },
  "request_id": "req_abc123"
}

Solution: Retry after a brief wait. If the issue persists, contact support with the request_id.

`upstream_provider_error`

{
  "error": {
    "message": "An upstream provider error occurred. Retry your request after a brief wait.",
    "type": "server_error",
    "param": null,
    "code": "upstream_provider_error"
  }
}

Solution: This is a temporary issue with our AI providers. Retry after a brief wait.

Service Unavailable Errors (503)

These errors indicate temporary service issues.

`service_overloaded`

{
  "error": {
    "message": "The service is currently overloaded. Please retry your request after a brief wait.",
    "type": "service_unavailable",
    "param": null,
    "code": "service_overloaded"
  }
}

Solution: Retry with exponential backoff.

`model_overloaded`

{
  "error": {
    "message": "Model 'veo-3' is experiencing high traffic. Please retry later or use an alternative model.",
    "type": "service_unavailable",
    "param": null,
    "code": "model_overloaded"
  }
}

Solution: Try an alternative model or retry later.

`model_unavailable`

{
  "error": {
    "message": "Model '<model_key>' is offline and does not accept new tasks.",
    "type": "service_unavailable",
    "param": null,
    "code": "model_unavailable"
  }
}

The model is not accepting new submissions. No task is created and no credits are reserved. If the message says the model is offline, do not retry; choose a model listed in GET /pricing. If the message says the model is temporarily unavailable, retry later.

`maintenance_mode`

{
  "error": {
    "message": "The service is under maintenance. Please try again later.",
    "type": "service_unavailable",
    "param": null,
    "code": "maintenance_mode"
  }
}

Solution: Wait for maintenance to complete. Check our status page for updates.

`moderation_unavailable`

{
  "error": {
    "message": "Content moderation is temporarily unavailable. Retry after a brief wait.",
    "type": "service_unavailable",
    "param": null,
    "code": "moderation_unavailable"
  }
}

Solution: Retry after a brief wait with exponential backoff. No credits were reserved.

Error Handling Best Practices

Implement Retry Logic

Always implement retry logic with exponential backoff for transient errors (429, 500, 503):

import time
import random

def retry_with_backoff(func, max_retries=3, base_delay=1):
    for attempt in range(max_retries):
        try:
            return func()
        except (RateLimitError, ServerError) as e:
            if attempt == max_retries - 1:
                raise
            delay = base_delay * (2 ** attempt) + random.uniform(0, 1)
            time.sleep(delay)

Log Request IDs

Always log the request_id from error responses. This helps our support team diagnose issues quickly.

Handle Specific Error Codes

Handle specific error codes rather than just HTTP status codes for more precise error handling:

try:
    response = api.generate_video(...)
except APIError as e:
    if e.code == "insufficient_credits":
        notify_user_to_top_up()
    elif e.code == "rate_limit_exceeded":
        retry_later(e.retry_after)
    else:
        log_error(e.request_id)