Error Handling · Token360

Token360 uses OpenAI-compatible error responses. All errors follow a consistent format, making it easy to handle them in your application.

Error Response Format

JSON

1{
2  "error": {
3    "message": "A human-readable description of the error",
4    "type": "error_type",
5    "param": "parameter_name",
6    "code": "error_code"
7  }
8}

Fields


`message`	string	Detailed description of what went wrong
`type`	string	Error category (see table below)
`param`	string or null	The parameter that caused the error, if applicable
`code`	string or null	A machine-readable error code

Error Types


`invalid_api_key`	Invalid or missing API key
`invalid_request_error`	Malformed request or invalid parameters
`not_found_error`	The requested resource does not exist
`model_not_found`	The requested model does not exist
`api_key_frozen`	Your API key has been frozen
`model_access_denied`	You don't have permission to access this model
`rate_limit_error`	Too many requests in a given time period
`insufficient_balance`	Insufficient account balance
`api_error`	Server-side error from Token360 or the model service

HTTP Status Codes


`400`	Bad Request	Invalid parameters, missing required fields
`401`	Unauthorized	Invalid API key, expired token
`402`	Payment Required	Insufficient account balance
`403`	Forbidden	API key frozen, or insufficient permissions for the requested model
`404`	Not Found	Model not found, resource does not exist
`429`	Too Many Requests	Rate limit or quota exceeded
`500`	Internal Server Error	Server-side error
`502`	Bad Gateway	Upstream provider unavailable
`503`	Service Unavailable	Service temporarily overloaded

Common Errors and Solutions

401: Invalid API Key

JSON

1{
2  "error": {
3    "message": "Invalid API key or token provided",
4    "type": "invalid_api_key",
5    "code": "401"
6  }
7}

Fix: Verify your API key is correct and includes the Bearer prefix in the Authorization header.

404: Model Not Found

JSON

1{
2  "error": {
3    "message": "The requested model does not exist",
4    "type": "model_not_found",
5    "param": "model",
6    "code": "404"
7  }
8}

Fix: Check the model name. Use GET /v1/models to list available models.

429: Rate Limit Exceeded

JSON

1{
2  "error": {
3    "message": "Rate limit exceeded. Please slow down your requests",
4    "type": "rate_limit_error",
5    "code": "429"
6  }
7}

Fix: Implement exponential backoff. Wait and retry:

Python

1import time
2import random
3
4def call_with_retry(func, max_retries=3):
5    for attempt in range(max_retries):
6        try:
7            return func()
8        except Exception as e:
9            if "rate_limit" in str(e) and attempt < max_retries - 1:
10                wait = (2 ** attempt) + random.random()
11                time.sleep(wait)
12            else:
13                raise

500: Internal Server Error

JSON

1{
2  "error": {
3    "message": "An internal error occurred",
4    "type": "api_error",
5    "code": "500"
6  }
7}

Fix: This is a server-side issue. Retry after a brief delay. If persistent, check the status page or contact support.

Best Practices

Always check HTTP status codes before parsing the response body.
Implement retries with exponential backoff for 429 and 5xx errors.
Set reasonable timeouts (30 seconds for standard requests, longer for streaming).
Log error responses including the traceId if present — it helps support debug issues.
Don't retry 400 or 401 errors — these indicate a problem with your request that won't resolve by retrying.

Error Handling with OpenAI SDK

The OpenAI SDK raises typed exceptions that you can catch:

Python

1from openai import OpenAI, APIError, RateLimitError, AuthenticationError
2
3client = OpenAI(
4    api_key="sk-your-api-key",
5    base_url="https://api.token360.ai/v1"
6)
7
8try:
9    response = client.chat.completions.create(
10        model="glm-5.1",
11        messages=[{"role": "user", "content": "Hello"}]
12    )
13except AuthenticationError:
14    print("Invalid API key")
15except RateLimitError:
16    print("Rate limited - implement backoff")
17except APIError as e:
18    print(f"API error: {e.message}")