Banned, Rate-Limited or Out of Credit? Reading Error Codes Before You Panic

Understanding API Error Responses

When you call an LLM API, a non-200 HTTP status code means something went wrong. The response body often contains a structured error with a type, code, and message. Reading these correctly saves time and prevents unnecessary panic.

Common Error Categories

Most LLM APIs group errors into a few families:

• Authentication errors (401/403): Invalid or missing API key, or a key that lacks permission for the requested model.
• Rate limit errors (429): You've exceeded the allowed request or token rate.
• Quota/credit errors (402 or 429): Your account balance is insufficient to cover the request.
• Model access errors (403/404): The model name is misspelled, deprecated, or not enabled for your account.
• Server errors (500/503): The provider is temporarily unavailable.

Banned vs. Rate-Limited vs. Out of Credit

These three are often confused, but they have different causes and fixes.

Banned (403 Forbidden)

A 403 typically means your API key or account has been blocked. Common reasons:

• Violation of the provider's usage policies.
• Suspicious activity detected on the key.
• The key was revoked by an administrator.

What to do: Check the error message for specifics. If you believe it's a mistake, contact support. Do not retry immediately; repeated attempts may worsen the situation.

Rate-Limited (429 Too Many Requests)

A 429 means you're sending requests too quickly or have hit a daily/monthly cap. The response may include headers like Retry-After or X-RateLimit-Reset.

What to do:

• Wait for the indicated time before retrying.
• Implement exponential backoff in your code.
• If you consistently hit limits, consider upgrading your plan or optimizing your request pattern.

Out of Credit (402 Payment Required or 429 with quota message)

This indicates your prepaid balance is zero or insufficient for the request. Unlike rate limits, waiting won't help.

What to do: Top up your account. On our platform, you can add USDC on Base without KYC. Your balance is used to pay for API calls at the official price × 1.3.

Reading the Error Payload

Always parse the JSON error body. Look for:

• error.type or error.code: A machine-readable string like insufficientquota or ratelimit_exceeded.
• error.message: A human-readable explanation.
• error.param: If the error relates to a specific parameter.

Example structure (varies by provider):

{
  "error": {
    "message": "You exceeded your current quota, please check your plan and billing details.",
    "type": "insufficient_quota",
    "code": "insufficient_quota"
  }
}

Handling Errors in Code

A robust client should:

• Retry on 429 and 5xx with exponential backoff.
• Not retry on 401, 403, or 402 (except after fixing the underlying issue).
• Log the full error response for debugging.

When to Contact Support

If you receive a 403 that you cannot explain, or a 402 despite having a positive balance, reach out. Include the full error response and the request ID (if provided) to speed up resolution.

Summary

• 403 Banned: Key or account blocked; contact support.
• 429 Rate-Limited: Slow down; retry after the indicated time.
• 402 Out of Credit: Top up; waiting won't help.

Understanding these distinctions helps you respond correctly and avoid unnecessary panic.

Note: Error codes and messages may vary slightly between providers. Always refer to the specific API documentation for exact meanings.