Guides
Errors & limits
What can go wrong, what to do about it, and how much you can send.
On this page
Errors
Errors use the OpenAI shape. Branch on
error.code (stable); message is for humans and may change.{
"error": {
"message": "Insufficient credits. Top up your wallet at https://platform.ditfa.com/credits.",
"type": "payment_required",
"code": "insufficient_credits",
"param": null
}
}| Status | Code | Meaning | Retry? |
|---|---|---|---|
| 400 | nullinvalid_request_error | The body is not valid JSON, model or messages is missing, or the model rejected the parameters. The message names the problem. | No |
| 401 | missing_api_keyauthentication_error | No Authorization: Bearer header was sent. | No |
| 401 | invalid_api_keyauthentication_error | The key is malformed, wrong, disabled or deleted. | No |
| 401 | wrong_key_typeauthentication_error | A Plan API key (dt-…) was sent to Ditfa Platform. Platform keys start with sk-dp-. | No |
| 401 | key_expiredauthentication_error | The key passed its expiry date. | No |
| 402 | insufficient_creditspayment_required | Available credits cannot cover the reserved cost of this request. Add credits or lower max_tokens. | No |
| 402 | key_limit_reachedpayment_required | The key reached its own spend limit for the current period. Raise the limit or wait for the next period. | No |
| 402 | sponsorship_exhaustedpayment_required | The sponsored offer on this model has run out of budget. | No |
| 402 | sponsorship_endedpayment_required | The free or sponsored offer on this model has ended. | No |
| 402 | sponsorship_pausedpayment_required | The free or sponsored offer on this model is paused. | No |
| 403 | account_disabledpermission_error | The account that owns the key cannot use the API. Contact support. | No |
| 403 | ip_not_allowedpermission_error | The request came from an IP outside the key's allowlist. | No |
| 403 | model_not_allowedpermission_error | The key's allowed-models list does not include this model. | No |
| 403 | no_allowed_providerpermission_error | No provider of this model matches the key or account provider settings (verified providers only / no prompt logging). | No |
| 403 | free_not_eligiblepayment_required | This account does not qualify for the offer yet: it needs a verified email, or it is too new. | No |
| 403 | free_access_disabledpayment_required | Free access to this model is turned off. | No |
| 403 | sponsorship_not_startedpayment_required | The free or sponsored offer on this model has not started yet. | No |
| 403 | wallet_frozenpayment_required | This account's Platform wallet is frozen. Contact support. | No |
| 404 | model_not_foundinvalid_request_error | The model slug does not exist or is not published. | No |
| 404 | not_foundinvalid_request_error | /generation: no request with this id belongs to your account. | No |
| 429 | rate_limit_exceededrate_limit_error | Too many requests per minute for this key, or from one IP address. Wait for the retry-after header. | Yes |
| 429 | model_overloadedrate_limit_error | Every provider of this model is busy right now. | Yes |
| 429 | free_quota_exceededrate_limit_error | Your limit on this free or sponsored model is used up. | After reset |
| 429 | free_capacity_exhaustedrate_limit_error | The allowance shared by everyone on this free or sponsored model is used up. | After reset |
| 429 | free_concurrency_limitrate_limit_error | Too many requests at once on this offer. Wait for one to finish. | Yes |
| 502 | upstream_unavailableserver_error | No provider could serve the request. You are not charged. | Yes |
| 502 | upstream_errorserver_error | The provider returned an unreadable response. You are not charged. | Yes |
Handling errors
Retry only 429 and 5xx, with exponential backoff and jitter, and honour retry-after. Treat 401, 402, 403 and 404 as configuration problems: retrying will not help.
free_quota_exceeded and free_capacity_exhausted are the 429s a quick retry will not fix: wait for the reset, or choose the normal price.
import OpenAI from 'openai';
const client = new OpenAI({
baseURL: 'https://gateway.ditfa.com/v1',
apiKey: process.env.DITFA_API_KEY,
maxRetries: 3, // retries 429 and 5xx with backoff, honouring retry-after
});
try {
const completion = await client.chat.completions.create({
model: 'openai/gpt-4o-mini',
messages: [{ role: 'user', content: 'Hello' }],
});
console.log(completion.choices[0].message.content);
} catch (error) {
if (error instanceof OpenAI.APIError) {
switch (error.code) {
case 'insufficient_credits':
case 'key_limit_reached':
// Not retryable: alert someone to top up or raise the key limit.
break;
case 'model_not_found':
case 'model_not_allowed':
// Fix the model slug or the key's allowed models.
break;
default:
console.error(error.status, error.code, error.message);
}
}
throw error;
}Used the wrong key?
A
dt- key sent to Ditfa Platform (or an sk-dp- key sent to the Plan API) gets 401 wrong_key_type with a message that says which product it belongs to.Rate limits & quotas
| Limit | Value |
|---|---|
| Requests per key | 600 per minute by default. Read x-ratelimit-* headers on every response. |
| Requests per IP | 1,000 per minute across all keys from one address. |
| Active keys | 25 per account. |
| Top-up size | $5 to $1,000 per payment; credits do not expire. |
| Default output cap | 16,384 tokens, or the model's maximum when lower. Set max_tokens to change it. |
| Context & max output | Per model; see /models or each model page. |
Need a higher request rate? Contact us with your expected volume.