MiniMax API Error Codes: Fixes and Debugging Guide

Last verified: July 20, 2026

When a MiniMax API request fails, do three things before changing your code: capture the full response body, identify the MiniMax-specific error code, and separate retryable failures from request, authentication, billing, or quota problems.

MiniMax’s official error-code reference lists common API codes such as 1002 for rate limit, 1004 for authorization/API key mismatch, 1008 for insufficient balance, 2013 for invalid parameters, 2049 for invalid API key, and 2056 for usage-limit exhaustion.

This guide turns those codes into a practical debugging workflow for developers using MiniMax through the native API, OpenAI-compatible API, Anthropic-compatible API, SDKs, tool calling, speech, image, video, file, or voice workflows.

Fast triage: what to check first

Use this quick checklist before going deep:

Log both layers of the failure: the HTTP status code and the MiniMax error code/message.
If the code is 1000, 1001, 1024, or 1033: treat it as likely temporary and retry later with backoff.
If the code is 1002, 1041, or 2045: reduce request rate, concurrency, or traffic spikes.
If the code is 1004 or 2049: verify the API key, key type, environment variable, base URL, and auth header.
If the code is 2013: validate the request body, endpoint, model name, message roles, tool schema, parameter types, and media/file IDs.
If the code is 1008 or 2056: check balance, assigned resources, Token Plan quota, and usage windows.
If the code is 1026, 1027, or 1042: treat it as a content-safety or input-sanitization issue. For 1026, revise the input; for 1027, revise the prompt or context that led to sensitive output; for 1042, remove invisible or illegal characters.
If the code is voice/audio-specific: verify file_id, voice_id, duration, prompt audio, and ownership/access.

MiniMax’s OpenAI-compatible Chat Completions example shows a successful response with base_resp.status_code: 0 and base_resp.status_msg: "", so when debugging MiniMax-specific responses, preserve these fields when they appear. A GSD community report shows a compatibility-layer HTTP 400 error containing MiniMax code 2013, and an OpenFang community report shows an HTTP 401 auth error containing MiniMax code 2049. These community reports are not official MiniMax documentation, but they support the practical logging recommendation: capture both the transport status and the provider error body.

MiniMax API error codes quick reference

The table below is based on MiniMax’s official Error Codes page. The “likely category,” “retry?” and “prevention” columns are practical engineering interpretations of the official message and solution, not separate MiniMax policy statements.

Code	Official message	Likely category	What it usually means	Recommended fix	Retry?
`1000`	`unknown error`	Temporary / server-side	The request failed for an unspecified reason.	Retry later; log the full response for correlation.	Yes, with backoff
`1001`	`request timeout`	Temporary / latency	The request did not complete in time.	Retry later; reduce request size if timeouts repeat.	Yes, with backoff
`1002`	`rate limit`	Rate limit	You exceeded a rate-control threshold.	Slow down, queue requests, reduce concurrency, and check RPM/TPM limits.	Yes, after delay
`1004`	`not authorized / token not match group / cookie is missing, log in again`	Authentication / authorization	The credential is missing, invalid for the group, or not active.	Verify the API key, key type, auth header, and environment variable.	No
`1008`	`insufficient balance`	Billing / account	The account lacks usable balance or resources.	Check billing balance, Token Plan resources, or assigned team resources.	No
`1024`	`internal error`	Temporary / server-side	MiniMax encountered an internal service error.	Retry later; escalate if persistent.	Yes, with backoff
`1026`	`input new_sensitive`	Content / safety	The input triggered a sensitivity/content restriction.	Change the input content; do not attempt to bypass safety filters.	No
`1027`	`output new_sensitive`	Content / safety	The model output triggered a sensitivity/content restriction.	Modify the prompt or input context.	No
`1033`	`system error / mysql failed`	Temporary / system	A backend system dependency failed.	Retry later; escalate if persistent.	Yes, with backoff
`1039`	`token limit`	Token / context	Token usage exceeded or hit a limit condition.	Reduce input/context, lower output tokens, or check model limits.	Usually after adjustment
`1041`	`conn limit`	Concurrency	Too many simultaneous connections or active requests.	Reduce concurrency; contact MiniMax if it persists.	After reducing load
`1042`	`invisible character ratio limit`	Input validation	Input contains too many invisible or illegal characters.	Normalize, sanitize, and validate text before sending.	No
`1043`	`The asr similarity check failed`	Speech / ASR	Voice/audio validation did not match expected text or file data.	Check `file_id` and `text_validation`.	No
`1044`	`clone prompt similarity check failed`	Voice cloning	Prompt audio and prompt words do not match enough.	Check clone prompt audio and prompt words.	No
`2013`	`invalid params / glyph definition format error`	Request validation	Request body, schema, endpoint, model, or parameter type is invalid.	Validate parameters against the exact endpoint documentation.	No
`20132`	`invalid samples or voice_id`	Voice / TTS	Invalid voice samples, `file_id`, or `voice_id`.	Check `file_id` for Voice Cloning and `voice_id` for T2A APIs.	No
`2037`	`voice duration too short / voice duration too long`	Voice cloning	The uploaded voice sample duration is outside the accepted range.	Adjust the duration of the voice-clone file.	No
`2039`	`voice clone voice id duplicate`	Voice cloning	The requested `voice_id` already exists.	Use a unique `voice_id`.	No
`2042`	`You don’t have access to this voice_id`	Authorization / voice	The account does not own or cannot access the `voice_id`.	Verify ownership/access or contact MiniMax if needed.	No
`2045`	`rate growth limit`	Traffic-shaping	Request volume is changing too abruptly.	Avoid sudden traffic spikes; ramp traffic gradually.	After reducing spike
`2048`	`prompt audio too long`	Audio validation	Prompt audio exceeds the allowed duration.	Keep `prompt_audio` shorter than 8 seconds.	No
`2049`	`invalid API Key`	Authentication	The API key is wrong, inactive, expired, or being used with the wrong surface.	Verify key, base URL, auth header, and environment variable.	No
`2056`	`usage limit exceeded`	Quota / usage window	A usage window or quota has been exhausted.	Wait for the next 5-hour resource window or adjust usage.	After quota resets

HTTP status codes vs MiniMax API error codes

Do not debug MiniMax failures from the HTTP status alone.

A request can fail at different layers:

Layer	Example	What it tells you	What to log
Transport / HTTP	`400`, `401`, `429`, `500`	Whether the HTTP request was accepted, rejected, throttled, or failed server-side.	HTTP status, endpoint, method, response body.
MiniMax API code	`2013`, `2049`, `1002`	The provider-specific failure reason.	MiniMax code, message, `base_resp` fields if present, request ID if present.
SDK / gateway layer	SDK exception, proxy error, router error	The client or gateway may have transformed the response.	SDK name/version, provider config, base URL, headers used minus secrets.

For example, public reports show 2013 appearing inside HTTP 400 invalid-parameter failures and 2049 appearing inside HTTP 401 authentication failures. These community examples are useful for recognizing patterns, but MiniMax’s official Error Codes page remains the source of truth for the meaning of the codes.

Fixing the most common MiniMax API errors

Error `2013`: invalid params / glyph definition format error

2013 is the error to investigate when the request body is structurally wrong. MiniMax’s official solution is to check the request parameters.

In practice, check these items in order:

Endpoint and format
- OpenAI-compatible calls should use the OpenAI-compatible endpoint and schema.
- Anthropic-compatible calls should use the Anthropic-compatible endpoint and schema.
- Do not mix message formats, headers, or base URLs from different compatibility layers.
Model name
- Confirm the model name is available for the API surface you are using.
- MiniMax’s API overview lists MiniMax-M3 and M2-series models for LLM use, and notes that the LLM API can be accessed via HTTP requests, the Anthropic SDK, or the OpenAI SDK.
Message roles and content blocks
- Verify that roles are accepted by the endpoint.
- Verify that multimodal content is sent only to models and endpoints that support it.
- MiniMax’s Anthropic-compatible Messages API states that MiniMax-M3 supports text, image, video, tool use, tool result, and thinking content blocks, while M2.7, M2.5, M2.1, and M2 series support text and tool-call content blocks only.
Parameter names and types
- Check for null where an integer/string/object is required.
- Check boolean values, enum values, array structure, nested tool definitions, and media object structure.
- Community reports around 2013 include invalid function-argument JSON and affected tool_call_id values, while another community report shows empty function names or parameters. Treat these reports as debugging examples rather than official MiniMax policy, and validate tool schemas, serialized arguments, function names, and tool result IDs carefully.
Token and context limits
- If the message says context or token limit, reduce the input context, reduce requested output, or split the task.
- MiniMax’s API overview notes that maximum token count refers to total input and output tokens for LLM context windows.
Media/file references
- If the request includes file_id, voice_id, images, videos, or audio, verify that the file exists, belongs to the account, is supported by that endpoint, and meets size/duration rules.

Minimal `2013` debugging checklist

Before retrying a 2013, print or inspect:

- HTTP method and endpoint
- Base URL
- Model name
- Auth header type, without printing the key
- Content-Type
- Full JSON body after serialization
- Message roles
- Tool definitions
- Tool call IDs and tool result IDs
- File IDs and voice IDs
- max_tokens or max_completion_tokens
- Any gateway/provider transformation

A plain retry usually will not fix 2013 unless the error was caused by an intermittent gateway transformation. Treat it as a request-shape problem first.

Error `2049`: invalid API Key

2049 means MiniMax rejected the API key as invalid. The official guidance is to check that the API key is correct and active.

Check these common causes:

The key is copied with an extra space, missing character, or wrong prefix.
The environment variable points to an old key.
The key belongs to a different MiniMax account, team, region, or plan.
A gateway, SDK, or deployment secret is still using a cached old key.
The key is used with the wrong base URL.
You are mixing Pay-as-you-go API keys and Token Plan subscription keys.
Your code sets both Authorization and x-api-key, and the wrong one takes precedence.
A browser/client-side app exposes or mutates the key.

MiniMax’s prerequisites page recommends exporting API credentials as environment variables, using ANTHROPIC_BASE_URL=https://api.minimax.io/anthropic with ANTHROPIC_API_KEY, or OPENAI_BASE_URL=https://api.minimax.io/v1 with OPENAI_API_KEY. MiniMax’s API overview also says Pay-as-you-go API Keys and Token Plan Subscription Keys are separate.

Quick key verification with OpenAI-compatible models endpoint

MiniMax’s OpenAI-compatible List Models endpoint uses GET /v1/models with Authorization: Bearer <token>.

curl --request GET \
  --url https://api.minimax.io/v1/models \
  --header "Authorization: Bearer <MINIMAX_API_KEY>"

If this fails with 2049, test the exact key value loaded by your runtime, not the value you think is loaded.

Quick key verification with Anthropic-compatible models endpoint

MiniMax’s Anthropic-compatible List Models endpoint uses GET /anthropic/v1/models and documents X-Api-Key authentication for that endpoint.

curl --request GET \
  --url https://api.minimax.io/anthropic/v1/models \
  --header "X-Api-Key: <MINIMAX_API_KEY>"

For the Anthropic-compatible Messages API, MiniMax also documents Authorization: Bearer <API_KEY> and notes that if both Authorization and x-api-key are present, Authorization takes precedence. The safest rule is simple: follow the exact authentication header shown for the endpoint or SDK you are calling, and avoid sending conflicting credentials.

Error `1004`: not authorized / token not match group / cookie is missing

1004 is also an authentication or authorization error, but its official message is broader than 2049. MiniMax describes it as “not authorized / token not match group / cookie is missing” and tells developers to check that the API key is correct and active.

Use this fix order:

Confirm the key is active in the MiniMax console.
Confirm the key belongs to the same account/team/group as the resource being used.
Confirm the right key type: Pay-as-you-go API key vs Token Plan subscription key.
Confirm the base URL matches the SDK mode.
Confirm the request is server-side, not from exposed browser code.
Rotate the key if you suspect leakage, then update all runtime secrets.

Error `1002`: rate limit

1002 means the request hit a rate limit. MiniMax’s rate-limit documentation defines rate limits as restrictions on how many times a user or client can access services within a specified period, and says LLM limits are divided into RPM and TPM.

MiniMax’s official rate-limit page lists current LLM examples such as MiniMax-M3 at 200 RPM and 10,000,000 TPM, and M2-series entries at 500 RPM and 20,000,000 TPM; the same page also lists modality-specific RPM limits for video, speech, image, and music APIs. Treat these as current-at-verification values and re-check the official page before publishing or changing production limits.

Fix 1002 with:

client-side request queues;
per-model rate-limit buckets;
exponential backoff with jitter;
lower concurrency;
request batching only when supported by the endpoint;
shorter prompts and outputs if TPM is the bottleneck;
alerting when usage approaches RPM or TPM ceilings.

Do not blindly retry every rate-limit error immediately. That usually makes the limit worse.

Error `2056`: usage limit exceeded

MiniMax’s official solution for 2056 is to wait for resource release in the next 5-hour window.

This is different from a simple per-minute rate limit. It can indicate that a broader quota or plan window is exhausted. MiniMax’s Token Plan FAQ says Token Plan quota uses 5-hour rolling and weekly quota windows, and that pay-as-you-go is recommended for production use.

Fix it by checking:

account usage dashboard;
Token Plan quota;
team resource assignment;
whether your workload is interactive or production;
whether background jobs are consuming quota;
whether a gateway or agent is creating more calls than expected.

Error `1008`: insufficient balance

1008 means the account lacks sufficient balance. MiniMax’s official guidance is to check account balance.

Do not solve this in application code with retries. Instead:

confirm billing balance;
confirm the correct account/team is used;
confirm whether the workload uses Pay-as-you-go or Token Plan resources;
confirm assigned team resources;
pause nonessential jobs until balance is restored.

Errors `1000`, `1001`, `1024`, and `1033`: temporary or server-side failures

These codes usually belong in the retryable bucket:

Code	Meaning	Practical handling
`1000`	Unknown error	Retry with backoff; log payload.
`1001`	Request timeout	Retry; reduce payload if repeated.
`1024`	Internal error	Retry later; escalate if persistent.
`1033`	System error / MySQL failed	Retry later; escalate if persistent.

MiniMax’s official solutions for these errors are to retry later.

Recommended retry policy:

Attempt 1: immediate failure captured
Attempt 2: wait ~1s + jitter
Attempt 3: wait ~2s + jitter
Attempt 4: wait ~4s + jitter
Attempt 5: stop, surface a controlled error, and alert if production-impacting

Use idempotency safeguards in your own system. Never retry a request that could create duplicate user-visible side effects unless your application can safely deduplicate it.

Error `1039`: token limit

MiniMax officially lists 1039 as token limit and suggests retrying later. In real integrations, however, token-limit failures often require request changes, not only waiting.

Check:

total input + output token budget;
max_tokens or max_completion_tokens;
long conversation history;
retrieved documents;
tool results copied into context;
image/video token usage;
model-specific context limits.

MiniMax’s Anthropic-compatible documentation says MiniMax-M3 supports token estimation through POST /anthropic/v1/messages/count_tokens, which returns input token usage without generating output. Use token counting before sending very large requests.

Error `1042`: invisible character ratio limit

1042 means MiniMax detected too many invisible or illegal characters in the input. The official solution is to check input content for invisible or illegal characters.

Common sources include:

copied text from PDFs;
zero-width spaces;
malformed Unicode;
hidden control characters;
OCR artifacts;
pasted HTML or email content;
untrusted user input.

Before sending user-provided text, normalize it:

import unicodedata

def normalize_for_minimax(text: str) -> str:
    normalized = unicodedata.normalize("NFKC", text)
    # Remove most control characters except common whitespace.
    return "".join(
        ch for ch in normalized
        if ch in "\n\t\r" or not unicodedata.category(ch).startswith("C")
    )

Errors `1026` and `1027`: sensitive input or output

MiniMax lists 1026 as input new_sensitive and 1027 as output new_sensitive, with the solution to change the input content.

Handle these as content-policy or safety-triggered failures:

do not retry the same prompt repeatedly;
do not attempt to bypass safety checks;
explain to the user that the request cannot be completed as written;
revise the task toward a safe, allowed request;
log only safe metadata, not the full sensitive content unless your privacy policy and security controls allow it.

Voice, speech, and audio-specific errors

Some MiniMax API error codes are specific to voice cloning, text-to-speech, ASR similarity, prompt audio, or voice IDs.

Code	Meaning	What to check
`1043`	ASR similarity check failed	Check `file_id` and `text_validation`.
`1044`	Clone prompt similarity check failed	Match prompt audio with prompt words.
`20132`	Invalid samples or `voice_id`	Verify `file_id` for Voice Cloning and `voice_id` for T2A APIs.
`2037`	Voice duration too short or too long	Adjust the file duration for voice clone.
`2039`	Duplicate voice clone `voice_id`	Use a unique `voice_id`.
`2042`	No access to this `voice_id`	Confirm ownership/access.
`2048`	Prompt audio too long	Keep `prompt_audio` under 8 seconds.

These definitions and official solutions are listed in MiniMax’s Error Codes reference.

OpenAI-compatible vs Anthropic-compatible MiniMax errors

MiniMax supports both OpenAI-compatible and Anthropic-compatible API usage. Its OpenAI SDK page says MiniMax supports the OpenAI API format and can be integrated through the OpenAI ecosystem with configuration changes. Its Anthropic SDK page documents Anthropic API compatibility and supported parameters/models for that interface.

Use this comparison when debugging:

Area	OpenAI-compatible MiniMax API	Anthropic-compatible MiniMax API
Base URL	`https://api.minimax.io/v1`	`https://api.minimax.io/anthropic` for SDK base URL; endpoint paths use `/anthropic/v1/...`
Common env vars	`OPENAI_BASE_URL`, `OPENAI_API_KEY`	`ANTHROPIC_BASE_URL`, `ANTHROPIC_API_KEY`
Typical auth	`Authorization: Bearer <token>`	Depends on endpoint/client; MiniMax documents both API key and bearer-style auth in Anthropic-compatible pages
Common mistakes	Wrong base URL, unsupported message role, wrong model name, invalid tool schema	Wrong content block type, conflicting auth headers, unsupported media on M2-series models, parameter mismatch
Best first test	`GET /v1/models`	`GET /anthropic/v1/models` or a minimal Messages request

MiniMax’s prerequisites page gives the recommended environment variables for Anthropic-compatible, OpenAI-compatible, and AI SDK usage.

Programmatic error handling pattern

A robust MiniMax integration should classify errors before deciding whether to retry, change the request, ask the user to revise input, or alert an engineer.

The parser below is intentionally defensive. It handles MiniMax-style base_resp fields when present and also attempts to extract a MiniMax code from compatibility-layer error messages that include a code in parentheses.

import json
import random
import re
import time
from typing import Any, Dict, Optional

TEMPORARY_RETRY_CODES = {1000, 1001, 1024, 1033}
THROTTLE_CODES = {1002, 1041, 2045}
AUTH_CODES = {1004, 2049}
BILLING_OR_QUOTA_CODES = {1008, 2056}
REQUEST_FIX_CODES = {1039, 1042, 2013, 20132, 2037, 2039, 2042, 2048}
SAFETY_CODES = {1026, 1027}

def extract_minimax_error(status_code: int, response_text: str) -> Dict[str, Any]:
    """
    Extracts a MiniMax error code from common response shapes.
    Never log secrets or full sensitive user prompts in production.
    """
    payload: Dict[str, Any] = {}

    try:
        payload = json.loads(response_text)
    except json.JSONDecodeError:
        return {
            "http_status": status_code,
            "minimax_code": None,
            "message": response_text[:500],
            "category": "non_json_error",
        }

    base_resp = payload.get("base_resp") or {}
    code: Optional[int] = base_resp.get("status_code")
    message = base_resp.get("status_msg") or ""

    # Compatibility-layer errors may put the provider message elsewhere.
    if code in (None, 0):
        error_obj = payload.get("error")
        if isinstance(error_obj, dict):
            message = error_obj.get("message") or message
        elif isinstance(error_obj, str):
            message = error_obj

        match = re.search(r"\((\d{4,5})\)", message or "")
        if match:
            code = int(match.group(1))

    if code in TEMPORARY_RETRY_CODES:
        category = "temporary_retryable"
    elif code in THROTTLE_CODES:
        category = "throttle_or_concurrency"
    elif code in AUTH_CODES:
        category = "auth"
    elif code in BILLING_OR_QUOTA_CODES:
        category = "billing_or_quota"
    elif code in REQUEST_FIX_CODES:
        category = "fix_request"
    elif code in SAFETY_CODES:
        category = "safety"
    else:
        category = "unknown"

    return {
        "http_status": status_code,
        "minimax_code": code,
        "message": message,
        "category": category,
    }

def should_retry(error: Dict[str, Any]) -> bool:
    code = error.get("minimax_code")
    return code in TEMPORARY_RETRY_CODES or code in THROTTLE_CODES

def backoff_sleep(attempt: int) -> None:
    delay = min(2 ** attempt, 30) + random.uniform(0, 0.5)
    time.sleep(delay)

Use the classifier like this:

for attempt in range(5):
    response = send_minimax_request()  # Replace with your HTTP client call.

    if response.ok:
        break

    error = extract_minimax_error(response.status_code, response.text)

    if should_retry(error):
        backoff_sleep(attempt)
        continue

    raise RuntimeError(
        f"MiniMax request failed: "
        f"http={error['http_status']} "
        f"code={error['minimax_code']} "
        f"category={error['category']} "
        f"message={error['message']}"
    )

Production debugging checklist

Use this checklist before escalating a MiniMax issue.

Request details

Endpoint and base URL.
HTTP method.
SDK name and version.
OpenAI-compatible, Anthropic-compatible, or native API mode.
Model name.
Request body after serialization.
Headers used, with API keys redacted.
Content-Type.
Whether streaming is enabled.
Whether tools/function calling are enabled.
File IDs, voice IDs, or media references, if used.

Account and quota details

Pay-as-you-go API key or Token Plan subscription key.
Current balance or resource assignment.
RPM and TPM usage.
5-hour and weekly usage windows if using Token Plan.
Concurrent workers, agents, or background jobs.
Recent traffic spikes.

MiniMax’s Rate Limits page explains RPM and TPM, and its Token Plan FAQ describes throttling, 5-hour rolling windows, and dynamic rate limiting during peak usage.

Safe logging rules

Log:

HTTP status;
MiniMax error code;
error message;
request ID if present;
model name;
endpoint;
SDK/provider mode;
retry count;
token usage if available;
sanitized request shape.

Do not log:

raw API keys;
bearer tokens;
full user prompts containing sensitive data;
private uploaded files;
unredacted audio/text content;
billing identifiers unless required and protected.

Retryable vs non-retryable MiniMax errors

Retry decision	Codes	Handling
Retry with backoff	`1000`, `1001`, `1024`, `1033`	Temporary/server-side; retry later with capped exponential backoff.
Retry after slowing down	`1002`, `1041`, `2045`	Reduce RPM, TPM, concurrency, or traffic spikes first.
Retry after quota/billing change	`1008`, `2056`	Resolve balance/resource/quota issue first.
Do not retry unchanged	`1004`, `2049`, `2013`, `1042`, voice/audio validation codes	Fix key, request body, input, media, or resource access first.
Ask for safer/revised input	`1026`, `1027`	Change the request content; do not bypass safety restrictions.

Common mistakes that cause MiniMax API errors

1. Mixing API surfaces

Do not use an OpenAI-style base URL with an Anthropic-style request body, or an Anthropic-style SDK with OpenAI-style message objects.

MiniMax documents separate OpenAI-compatible and Anthropic-compatible paths and SDK setup instructions.

2. Using the wrong model for media

MiniMax’s Anthropic-compatible Messages API states that MiniMax-M3 supports text, image, video, tool use, tool result, and thinking content blocks, while M2-series models do not accept image or video input. Sending image or video blocks to a text/tool-only model can lead to request validation failures.

3. Sending unsupported or ignored parameters

MiniMax’s Anthropic SDK documentation lists supported parameters and notes that some Anthropic parameters, such as top_k, stop_sequences, mcp_servers, context_management, and container, are ignored. It also says values outside the documented temperature range return an error. Validate parameters before sending requests through compatibility layers.

4. Treating Token Plan quotas like production capacity

MiniMax’s Token Plan FAQ says the Token Plan is designed for individual, interactive developer use and recommends pay-as-you-go for production use. If production jobs hit 2056, do not only add retries; review plan type, quota windows, and traffic pattern.

5. Retrying invalid requests

Retries help temporary failures. They do not fix malformed JSON, invalid voice_id, wrong message roles, expired keys, missing balance, or unsupported model inputs.

Before contacting MiniMax support

If the issue persists after local debugging, prepare a concise support packet:

- Date/time of failure with timezone
- Endpoint and API mode
- Model name
- HTTP status code
- MiniMax error code and message
- Request ID if present
- Whether streaming was enabled
- Sanitized request body
- SDK/client/library and version
- Whether the same key works against the List Models endpoint
- Current rate/concurrency level
- Whether this is Pay-as-you-go or Token Plan
- Steps to reproduce with secrets removed

Do not send raw API keys, private user content, or confidential uploaded files unless MiniMax support explicitly provides a secure process for doing so.

FAQ

What does MiniMax API error code `2013` mean?

2013 means invalid params / glyph definition format error according to MiniMax’s official Error Codes page. The official fix is to check the request parameters. In practice, validate the endpoint, request body, model name, message roles, tool schema, parameter types, and file or voice IDs.

How do I fix MiniMax `invalid params` errors?

Start by reproducing the failure with the smallest possible request. Then compare your JSON body against the exact endpoint documentation, remove optional parameters, verify model support, and inspect serialized tool/function payloads. Public reports around MiniMax 2013 errors frequently involve tool-call IDs, function arguments, empty parameters, or unsupported message roles.

Why am I getting MiniMax error `2049`?

2049 means invalid API Key. Check that the key is correct, active, loaded by the runtime, matched to the right account or plan, and used with the correct base URL and auth header. MiniMax also distinguishes Pay-as-you-go API keys from Token Plan subscription keys.

How do I fix MiniMax rate limit error `1002`?

Reduce request volume, concurrency, and token usage. MiniMax defines rate limits in terms of RPM and TPM for LLM usage, and its rate-limit tables vary by model and interface. Use a queue, exponential backoff with jitter, and per-model rate buckets.

Which MiniMax API errors should I retry?

Retry likely temporary errors such as 1000, 1001, 1024, and 1033. Retry 1002, 1041, and 2045 only after reducing request rate, concurrency, or traffic spikes. Do not retry 2013, 2049, 1004, 1008, or validation errors without fixing the underlying cause first. This retry classification is a practical interpretation of MiniMax’s official messages and solutions.

What is the difference between `1004` and `2049`?

Both are authentication-related. 2049 is specifically invalid API Key; 1004 covers authorization problems such as token mismatch, missing cookie, or not authorized. MiniMax’s official solution for both is to verify that the API key is correct and active.

Should I check the response body even when the HTTP status looks successful?

Yes. Do not rely on the HTTP status alone. MiniMax’s OpenAI-compatible Chat Completions example includes base_resp.status_code and base_resp.status_msg in the response body, with success shown as status_code: 0. When MiniMax-specific fields are present, log and inspect them alongside the HTTP status.

How can I prevent MiniMax token-limit errors?

Count or estimate tokens before sending large requests, truncate old conversation history, summarize tool results, reduce retrieved context, and set realistic output limits. For Anthropic-compatible MiniMax-M3 calls, MiniMax documents a POST /anthropic/v1/messages/count_tokens endpoint for input token estimation.

Why does my OpenAI-compatible or Anthropic-compatible MiniMax request fail?

The most common causes are mixed base URLs, wrong auth headers, unsupported parameters, unsupported message roles, wrong content block types, and models that do not support the media type being sent. MiniMax documents separate OpenAI-compatible and Anthropic-compatible setup instructions, so verify the exact SDK mode before changing the request.