Error Codes

Complete API error code reference with solutions. When an API call fails, use this guide to quickly identify the cause and take corrective action.

Error Response Format

All errors follow a unified JSON structure:

{
  "error": {
    "code": "invalid_request",
    "message": "Request body is malformed",
    "type": "invalid_request_error",
    "request_id": "req_abc123xyz"
  }
}

Field	Type	Description
code	string	Machine-readable error code for programmatic handling
message	string	Human-readable error description
type	string	Error type classification
request_id	string	Unique request identifier — include this when filing tickets

HTTP Status Codes

Status	Type	Description	Solution
400	invalid_request	Malformed request body	Check field types and required fields
401	authentication_error	API key invalid or missing	Verify your API key
403	permission_error	Insufficient API key perms	Check API key permission settings
404	not_found	Model or resource not found	Verify the model identifier
409	conflict	Resource conflict	Check the resource state
422	unprocessable_entity	Invalid request parameters	Check parameter values and allowed ranges
429	rate_limit_error	Rate limit exceeded	See Rate Limits
500	server_error	Internal server error	Retry with exponential backoff
502	bad_gateway	Gateway error	Retry shortly
503	service_unavailable	Upstream service unavailable	Retry shortly
504	gateway_timeout	Gateway timeout	Simplify the request or retry shortly

Error Code Details

invalid_request

HTTP Status: 400

The request body does not meet API requirements. This may be due to malformed JSON, missing required fields, or incorrect field types.

Common causes:

• Request body is not valid JSON
• Missing required fields like model or messages
• Incorrect field types (e.g., passing a string to messages instead of an array)

Solution:

# Incorrect
{"model": "deepseek-v4-flash", "messages": "Hello"}  # messages should be an array

# Correct
{"model": "deepseek-v4-flash", "messages": [{"role": "user", "content": "Hello"}]}

authentication_error

HTTP Status: 401

API key is missing, malformed, or has been revoked.

Common causes:

• No Authorization header provided
• Incorrect format (missing Bearer prefix)
• API key has been disabled or deleted

Solution:

# Ensure the header format is correct
Authorization: Bearer sk-your-api-key-here

Check your key status in the API Key Management page.

permission_error

HTTP Status: 403

API key exists but lacks sufficient permissions to access the requested resource.

Common causes:

• API key does not have access to the requested model
• Account verification is incomplete
• API key is restricted to specific IPs or domains

Solution:

• Review API key permissions in the Console
• Ensure your account has completed required verification

not_found

HTTP Status: 404

The requested model or resource does not exist.

Common causes:

• Model identifier is misspelled
• Model has been deprecated or is not yet available
• Task ID does not exist (for async task queries)

Solution:

• Confirm the model identifier in the Model List
• Double-check the model name, including version numbers and hyphens

insufficient_quota

HTTP Status: 402

Account balance is insufficient to complete the request.

Common causes:

• Account balance is zero or too low for the requested operation

Solution:

• Top up your balance in the Console
• Consider enabling balance alerts to avoid running out of funds

rate_limit_error

HTTP Status: 429

Request frequency exceeds the rate limit for your current tier.

Common causes:

• Too many requests in a short time window
• Too many concurrent requests

Solution:

• See Rate Limits for your tier's quotas
• Implement exponential backoff with jitter
• File a ticket if you need higher limits

import time
import random

def retry_with_backoff(func, max_retries=5):
    for attempt in range(max_retries):
        try:
            return func()
        except RateLimitError:
            wait = (2 ** attempt) + random.uniform(0, 1)
            time.sleep(wait)
    raise Exception("Max retries exceeded")

server_error

HTTP Status: 500

Internal server error — typically not caused by the request itself.

Solution:

• Retry with exponential backoff
• If the issue persists, record the request_id and submit a ticket

service_unavailable

HTTP Status: 503

The upstream model service is temporarily unavailable due to maintenance or overload.

Solution:

• Wait 30 seconds and retry
• Try switching to an alternative model if the issue persists
• Check platform announcements for maintenance schedules

Common Error Scenarios

"Model not found"

• Verify the model identifier in the Model List
• Check whether the model has been deprecated or is in Beta
• Confirm the model name is spelled correctly (including version numbers and hyphens)

"Insufficient quota"

• Check your account balance in the Console
• Top up your account
• Review billing details to understand your spending

"Rate limit exceeded"

• See Rate Limits for your tier's quotas
• Implement exponential backoff with jitter
• Reduce the number of concurrent requests
• Upgrade your tier or file a ticket for higher limits

Video generation task failure

• Check whether the prompt contains restricted content
• Ensure the image URL is accessible (for image-to-video scenarios)
• Simplify the prompt and retry
• If failures persist, record the task_id and submit a ticket

Error Handling Best Practices

1. Always check error.code: Use the error code (not just the HTTP status) for programmatic handling — it's more precise
2. Implement exponential backoff for retryable errors: 429 and 5xx errors are suitable for retry with jittered exponential backoff
3. Don't retry 400 errors: A 400 error means the request itself is flawed — fix the request before retrying
4. Record the request_id: Every error response includes a unique request_id — always provide it when submitting tickets
5. Set reasonable timeouts: Video generation and other async tasks may take longer, but set 30–60 second timeouts for synchronous endpoints
6. Monitor error rates: Log and analyze error types and frequencies in your application to detect anomalies early

Getting Help

If the above solutions don't resolve your issue:

• Submit a ticket in the Console with the request_id and error details
• Check the Request Logs to trace the detailed status of past requests