Skip to main content
When something goes wrong, the ShuttleAI API returns a JSON error response with an HTTP status code, error message, and error type.

​
Error response format

{
  "error": {
    "message": "Detailed error description",
    "type": "error_type",
    "code": 400
  }
}

​
Error codes

​
400 — Bad Request

Your request is malformed or missing required fields. Common causes:
  • Missing or empty messages array
  • Invalid model ID
  • Malformed JSON body
  • Invalid parameter values (e.g., temperature: 5)
Fix: Check your request body against the API reference.

​
401 — Unauthorized

Your API key is missing, invalid, or malformed. Common causes:
  • No Authorization header
  • API key doesn’t start with shuttle-
  • Typo in the API key
Fix: Double-check your API key. Make sure the header is Authorization: Bearer shuttle-xxx.

​
402 — Payment Required

You don’t have an active plan. Common causes:
  • No subscription on your account
  • Subscription has expired
  • Payment failed
Fix: Subscribe to a plan or check your billing page for payment issues.

​
403 — Forbidden

Your plan doesn’t include access to the requested model. Common causes:
  • Trying to use a Premium model on a Basic plan
  • Trying to use a Basic model on a Free plan
Fix: Upgrade your plan to access higher-tier models, or switch to a model available on your current tier.

​
423 — Locked

Your account has been suspended. Common causes:
  • Terms of service violation
  • Abuse detected
Fix: Contact support on Discord for more information.

​
429 — Too Many Requests

You’ve exceeded your rate limit. Common causes:
  • Sending more requests per minute than your plan allows
  • Not accounting for request multipliers
Fix: Wait until the next minute window and retry. Consider upgrading for higher rate limits.
Implement exponential backoff in your code to handle 429 errors gracefully:
import time

def make_request_with_retry(func, max_retries=3):
    for attempt in range(max_retries):
        try:
            return func()
        except Exception as e:
            if "429" in str(e) and attempt < max_retries - 1:
                time.sleep(2 ** attempt)  # 1s, 2s, 4s
            else:
                raise

​
500 — Internal Server Error

Something went wrong on our end. Fix: Wait a moment and retry. If the error persists, check status.shuttleai.com or report it on Discord.

​
503 — Service Unavailable

The requested model or service is temporarily unavailable. Common causes:
  • Model is undergoing maintenance
  • Upstream provider is down
  • High demand causing temporary capacity issues
Fix: Try a different model, or wait and retry. Check status.shuttleai.com for ongoing incidents.

​
Best practices

Never assume API calls will succeed. Wrap calls in try/catch and handle each error code appropriately.
For 429 and 5xx errors, retry with exponential backoff instead of immediately re-sending.
Log the full error response (message + type + code) to make debugging easier.
Use the Dashboard to understand your usage patterns and avoid hitting rate limits.