Error Handling

Token360 uses HTTP status codes and OpenAI-compatible error objects so applications can handle failures consistently.

This guide applies to OpenAI-compatible endpoints. If an endpoint page documents a different response envelope or a protocol-specific error format, follow that endpoint's documentation.

Error Response Format

1{
2  "code": "400",
3  "error": {
4    "message": "Missing required field: model",
5    "type": "invalid_request_error",
6    "param": "model",
7    "code": "invalid_request",
8    "traceId": "2c45dc1a-0e6a-4c8a-a095-6d0a40b4ad38"
9  },
10  "traceId": "2c45dc1a-0e6a-4c8a-a095-6d0a40b4ad38"
11}

Use the HTTP response status as the primary success or failure signal. Do not infer behavior from the human-readable message.

Fields

Additional endpoint-specific fields may be present. Clients should ignore fields they do not recognize.

Error Types

error.type identifies the broad category. error.code provides the more specific reason.

Endpoints may return additional documented types.

Common Error Codes

The same type can have more than one semantic code. These are common values, not an exhaustive list.

HTTP Status Codes

Common Examples

Invalid API Key

1{
2  "code": "401",
3  "error": {
4    "message": "Invalid API key or token provided",
5    "type": "invalid_request_error",
6    "code": "invalid_api_key",
7    "traceId": "2c45dc1a-0e6a-4c8a-a095-6d0a40b4ad38"
8  },
9  "traceId": "2c45dc1a-0e6a-4c8a-a095-6d0a40b4ad38"
10}

Verify the API key and send it as Authorization: Bearer sk-your-api-key. Do not retry until the credential is corrected.

Insufficient Balance or Quota

1{
2  "code": "402",
3  "error": {
4    "message": "Insufficient account balance. Please recharge",
5    "type": "insufficient_quota",
6    "code": "insufficient_quota",
7    "traceId": "2c45dc1a-0e6a-4c8a-a095-6d0a40b4ad38"
8  },
9  "traceId": "2c45dc1a-0e6a-4c8a-a095-6d0a40b4ad38"
10}

Add sufficient balance or quota before retrying. A quota-related 429 also requires resolving the quota condition rather than repeatedly retrying.

Rate Limit Exceeded

1{
2  "code": "429",
3  "error": {
4    "message": "Rate limit exceeded. Please slow down your requests",
5    "type": "rate_limit_error",
6    "code": "rate_limit_exceeded",
7    "traceId": "2c45dc1a-0e6a-4c8a-a095-6d0a40b4ad38"
8  },
9  "traceId": "2c45dc1a-0e6a-4c8a-a095-6d0a40b4ad38"
10}

Retry with exponential backoff and random jitter. Honor the Retry-After response header when it is present.

Temporary Service Error

1{
2  "code": "503",
3  "error": {
4    "message": "Service temporarily unavailable",
5    "type": "api_error",
6    "code": "server_error",
7    "traceId": "2c45dc1a-0e6a-4c8a-a095-6d0a40b4ad38"
8  },
9  "traceId": "2c45dc1a-0e6a-4c8a-a095-6d0a40b4ad38"
10}

Retry with exponential backoff when the operation is safe to repeat. If the error persists, contact support and include the correlation IDs.

Retry Guidance

• Retry transient 429, 500, 502, 503, and 504 responses with exponential backoff and jitter.
• Do not automatically retry 429 responses whose error.code is insufficient_quota.
• Do not automatically retry 400, 401, 402, 403, 404, 405, 409, 413, or 501 responses without first correcting the underlying condition.
• Set a maximum retry count and a total time limit.
• Retry only operations that are safe to repeat. Follow endpoint-specific idempotency guidance for create or submit operations.

Request IDs and Support

Responses can include X-Request-Id and X-Trace-ID headers in addition to the body traceId. Capture these values with the HTTP status, error.type, error.code, and optional serviceCode. Do not log API keys, authorization headers, or sensitive request content.

Error Handling with the OpenAI Python SDK

The OpenAI Python SDK maps HTTP errors to typed exceptions:

1from openai import (
2    APIConnectionError,
3    APIStatusError,
4    APITimeoutError,
5    AuthenticationError,
6    BadRequestError,
7    NotFoundError,
8    OpenAI,
9    PermissionDeniedError,
10    RateLimitError,
11)
12
13client = OpenAI(
14    api_key="sk-your-api-key",
15    base_url="https://api.token360.ai/v1",
16)
17
18try:
19    response = client.chat.completions.create(
20        model="claude-opus-5",
21        messages=[{"role": "user", "content": "Hello"}],
22    )
23except BadRequestError as exc:
24    print(f"Invalid request: {exc}")
25except AuthenticationError as exc:
26    print(f"Authentication failed: {exc}")
27except PermissionDeniedError as exc:
28    print(f"Permission denied: {exc}")
29except NotFoundError as exc:
30    print(f"Not found: {exc}")
31except RateLimitError as exc:
32    print(f"Rate limited; request_id={exc.request_id}")
33except (APITimeoutError, APIConnectionError) as exc:
34    print(f"Connection failed: {exc}")
35except APIStatusError as exc:
36    print(f"API error {exc.status_code}; request_id={exc.request_id}")

Before retrying a RateLimitError, inspect the response body's error.code: retry rate_limit_exceeded with backoff, but resolve insufficient_quota first.

Assets API error format

Assets endpoints use the Token360 response envelope. Use the HTTP status and serviceCode for program logic; treat msg as human-readable text whose wording may change.

1{
2  "code": 409,
3  "serviceCode": "ASSET_DELETE_USAGE_ACTIVE",
4  "data": null,
5  "msg": "The asset is currently in use",
6  "traceId": "2c45dc1a-0e6a-4c8a-a095-6d0a40b4ad38"
7}

Managed asset quota and deletion errors

The service deliberately uses the same not-found-or-not-authorized response where appropriate, so clients cannot use the API to discover assets outside their scope.