Errors & Troubleshooting

DDTokens is a model API gateway. Errors can originate from the DDTokens account system, the network path, or an upstream model provider. Identify the source before deciding whether to retry.

Common Error Types

Type	Common cause	Retry?
Authentication error	Invalid, disabled, or expired API key, or an incorrectly formatted header	No; fix the key first
Balance error	Insufficient account balance or token quota	No; top up or adjust the quota first
Rate-limit error	Request rate exceeds account or token limits	Yes, after backing off
Upstream error	Upstream model is overloaded, unavailable, or rejects request parameters	Depends on the error
Timeout error	Request exceeds a client, network, or gateway timeout	Retry after reducing output or changing strategy

Authentication Failure

Check the following:

1. The request header is Authorization: Bearer <API_KEY>.
2. The entire API key was copied.
3. The API key belongs to the current account.
4. The API key has not been disabled, deleted, or expired.

Insufficient Balance

The shortfall may be in the account balance or the individual token quota. Open the dashboard and check:

• Available account balance.
• Available quota for the current token.
• Whether the most recent failed request incurred a charge.

Rate Limit Reached

If you receive a 429 or similar rate-limit error, reduce concurrency and use exponential backoff:

1s -> 2s -> 4s -> 8s

Do not retry continuously without a delay. That prolongs recovery and may trigger stricter protection.

Upstream Errors

Upstream errors are usually related to the model provider, model parameters, or temporary capacity. You can try:

• Switching to a more stable model.
• Removing parameters whose support is uncertain.
• Reducing the output length.
• Checking for an unavailable model or provider prefix.

Before Contacting Support

To speed up diagnosis, provide:

• Request time.
• API key name, but never the full key.
• Model name.
• HTTP status code.
• Error response body.
• Request ID from the dashboard log, if available.