MaiToken
Login/Register

Error Codes

When calling the MaiToken API, you can identify issues using the HTTP status code and the business error code in the response body:

  • HTTP status codes indicate the overall result of request processing.
  • Business error codes are located in the error.code field of the response body and indicate the specific cause of the error.
  • Error types are located in the error.type field, allowing applications to consistently identify and handle similar exceptions.

We recommend troubleshooting based on the business error code first, then correcting the request according to the error message and recommended action. If the issue persists, provide technical support with the request time, business error code, and request ID (if included in the response). Do not provide your complete API Key.

Error Code HTTP Status Code Possible Cause Recommended Action
key_invalid 401 The API Key was not provided, or the API Key is incorrect or does not exist Check whether the API Key in the request header is complete and valid, and ensure it contains no extra spaces or characters
key_disabled 401 The current API Key has been disabled Check the Key status in the console, then enable the Key or create a new API Key
user_disabled 403 The account associated with the API Key has been disabled Check the account status; contact technical support if further assistance is required
ip_rejected 403 The current request IP is not included in the API Key’s IP allowlist Add the outbound IP to the allowlist or send the request from a network included in the allowlist
rate_limited 429 The request rate exceeds the current API Key or account rate limit Reduce concurrency or request frequency and retry using an exponential backoff strategy; contact technical support if you need a higher limit
key_quota_exhausted 429 The request quota for the current API Key or account has been exhausted Check the quota and usage in the console, adjust the quota, and retry
user_balance_exhausted 402 The account has insufficient available balance Top up or adjust the available balance, then retry
bad_request 400 The model name is missing from the request path or request body Specify the correct model parameter according to the API documentation
bad_request 400 The request body is empty, incorrectly formatted, or incomplete Check the JSON format, the Content-Type request header, and whether the request body is complete
bad_request 400 The model name in the request path does not match the model name in the request body Update the model names in the path and request body so they match
bad_request 413 The request body exceeds the maximum size allowed by the endpoint Reduce the request content or file size; request bodies for standard non-binary endpoints must be smaller than 32 MiB
model_not_found 404 The model name is incorrect, the current API Key is not authorized to use the model, or the model is temporarily unavailable Check the model name and Key permissions, and confirm that the model is currently available; retry later or use another model if necessary
task_not_found 404 The asynchronous task ID does not exist, the task does not belong to the current account, or the task record has expired Check the task ID and query it using the account and API Key that created the task
unsupported_endpoint 404 The requested endpoint path or operation is not currently supported Check the request URL and operation name against the API documentation
client_cancelled 499 The client disconnected or canceled the request before the service completed the response Check the client timeout settings and network connection; do not cancel the request early if the result is required
internal_error 500 The platform is currently busy processing requests and has temporarily rejected the request to ensure billing and data consistency Retry later; exponential backoff is recommended. Contact technical support if the issue persists
internal_error 503 The platform is temporarily unable to retrieve API Key authentication information Retry later; contact technical support if the issue persists
internal_error 503 The platform is temporarily unable to verify the account quota or balance Retry later and check the balance and quota status in the console
internal_error 503 The model service configuration is temporarily unavailable Retry later or use another available model; contact technical support if the issue persists
internal_error 503 The platform is temporarily unable to retrieve asynchronous task information Retry the query later using the original task ID; do not immediately create a duplicate task
upstream_rate_limited 429 The current model service is busy, and all available channels have triggered rate limiting Reduce the request frequency and retry later, or temporarily use another model
upstream_exhausted 502 The request could not be completed after attempting multiple model service channels Retry later or use another model; contact technical support if the issue persists
stream_interrupted_after_first_byte 200 The streaming response began, but the model service was interrupted during transmission; therefore, the HTTP status code remains 200 The client should also listen for error events within the stream; resend the request if required by your application

Error Response Example

The following example indicates that the API Key used for the request is invalid. The HTTP status code is 401, the business error code is key_invalid, and the error type is authentication_error:

{  "error": {    "code": "key_invalid",    "type": "authentication_error",    "message": "invalid api key"  }}

Client Handling Recommendations

  • When receiving a 400, 401, 402, 403, or 404 response, first check the request parameters, credentials, balance, permissions, and whether the resource exists. Correct the issue before retrying.
  • When receiving a 429 response, reduce the request frequency and retry using an exponential backoff strategy.
  • When receiving a 500, 502, or 503 response, retry after a short delay. Set a maximum number of retry attempts to prevent infinite retries.
  • For streaming requests, continue monitoring the response stream for error signals even when the HTTP status code is 200.
  • Do not submit your complete API Key in logs, support tickets, or chats.