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

JSON

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


`code`	string	The HTTP status code as a string.
`error.message`	string	A human-readable description intended for logs or display. The wording may change.
`error.type`	string	The broad error category.
`error.param`	string, optional	The request parameter associated with the error, when available.
`error.code`	string, optional	A machine-readable semantic code suitable for application logic.
`traceId`	string	A request correlation ID to include when contacting support.
`error.traceId`	string	The same correlation ID inside the OpenAI-compatible error object.
`serviceCode`	string, optional	An additional Token360 diagnostic code. When present, it may also appear as `error.serviceCode`; preserve it in logs and support requests.

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.


`invalid_request_error`	The request, a parameter, or a credential is invalid.
`authentication_error`	Authentication failed or the credential cannot be used.
`permission_error`	The credential is valid but cannot access the requested resource.
`not_found_error`	The requested resource does not exist.
`rate_limit_error`	The request exceeded an applicable rate or capacity limit.
`insufficient_quota`	The account or API key does not have sufficient balance or quota.
`api_error`	The request could not be completed because of a temporary service error.
`server_error`	Token360 encountered an unexpected server error.

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.


`invalid_request`	The request is invalid.	Correct the request before trying again.
`invalid_api_key`	The API key is missing, invalid, or unavailable for use.	Verify the credential and authorization header.
`model_not_found`	The requested model is unavailable to the caller.	Check the model name and access.
`insufficient_permissions`	The caller lacks the required permission.	Use a credential with the required access.
`rate_limit_exceeded`	A rate or capacity limit was reached.	Retry with backoff.
`insufficient_quota`	Available balance or quota is insufficient.	Add balance or quota, or use another eligible API key.
`request_too_large`	The request body exceeds the allowed size.	Reduce the request size.
`unsupported_feature`	The requested operation is not supported.	Remove the unsupported option or use a supported operation.
`stream_interrupted`	A streaming response ended with an error.	Treat the stream as failed and retry only when safe.
`server_error`	A temporary or unexpected service error occurred.	Retry with backoff when the operation is safe to repeat.

HTTP Status Codes


`400`	Bad Request	Correct invalid JSON, parameters, or required fields.
`401`	Unauthorized	Check the API key and `Authorization: Bearer ...` header.
`402`	Payment Required	Add sufficient account balance before retrying.
`403`	Forbidden	Check API-key status and model or resource access.
`404`	Not Found	Check the resource ID or model name.
`405`	Method Not Allowed	Use the HTTP method documented for the endpoint.
`409`	Conflict	Resolve the conflicting request state before retrying.
`413`	Content Too Large	Reduce the request body or uploaded content size.
`429`	Too Many Requests	Inspect `error.code`; back off for `rate_limit_exceeded`, but resolve quota issues for `insufficient_quota`.
`500`	Internal Server Error	Retry with backoff when safe.
`501`	Not Implemented	Use a supported operation.
`502`	Bad Gateway	Retry with backoff when safe.
`503`	Service Unavailable	Retry with backoff when safe.
`504`	Gateway Timeout	Retry with backoff when safe.

Common Examples

Invalid API Key

JSON

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

JSON

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

JSON

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

JSON

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:

Python

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.