Common API Errors¶

When the AI-VERDE API rejects a request, it returns an HTTP error status and a short JSON message. This page explains the errors you are most likely to see, what causes them, and whether you can fix them yourself or need to contact support.

Your client may show the raw JSON, a shortened message, or an exception name. Search the error text for the HTTP status (401, 403, 404, 429, and so on) and the type field, then find the matching section below.

Quick reference¶

What an error looks like¶

Most errors come back as JSON with an error object:

{
    "error": {
        "message": "Authentication Error, No api key passed in.",
        "type": "auth_error",
        "param": "None",
        "code": "401"
    }
}

message describes the problem. type names the error category, but some errors leave it empty (null or the string "None"). code repeats the HTTP status. Rely on the HTTP status first and use the message for detail.

401 Unauthorized: the API key was rejected¶

AI-VERDE could not match your request to a valid API key. Common causes:

• The key is missing from the request, or the client reads it from an environment variable that isn't set in the current shell.
• The key was copied with extra spaces or a missing character.
• The key belongs to a course or team that has ended, so it has expired.

The message tells you which case you hit:

To fix it, copy the key again from the API Key tab of your course details (see Obtaining your AI-VERDE API Key) and check that your client sends it. OpenAI-compatible clients send it as a bearer token:

Authorization: Bearer <your-ai-verde-api-key>

You can test the key on its own with curl. If this returns your model list, the key works and the problem is in your client configuration:

curl -s "https://llm-api.cyverse.ai/v1/models" -H "Authorization: Bearer $VERDE_API_KEY"

Retrying with the same key won't help. If a freshly copied key still fails, or the key has expired, email ai-verde-support@cyverse.org.

401 from the model provider¶

Sometimes your key is fine and the 401 comes from the provider behind AI-VERDE, such as AWS Bedrock. In that case the message contains litellm.AuthenticationError followed by the provider's own error text. Getting a new API key won't fix this. Email support with the full error message.

400 Bad Request: the model name is wrong¶

AI-VERDE doesn't recognize the model you asked for:

{
    "error": {
        "message": "/chat/completions: Invalid model name passed in model=claude-sonnet-5. Call `/v1/models` to view available models for your key.",
        "type": "None",
        "param": "None",
        "code": "400"
    }
}

This usually happens when you use the provider's public model name instead of the AI-VERDE name. Models provided for your course or team carry a course or team prefix, for example my-team-claude-sonnet-5 or my-team/claude-sonnet-5. CyVerse-hosted models such as gemma-4-26b-it have no prefix.

Copy the exact name from your model list. Getting a List of Models shows how to find it in the course details or with the API.

If the message instead contains litellm.NotFoundError with a 404 status, AI-VERDE recognized the name but the provider couldn't find the model. Email support.

403 Forbidden: no access to that model¶

The model exists, but your key isn't allowed to use it:

{
    "error": {
        "message": "key not allowed to access model. This key can only access models=['my-team-gemma-4-26b-it']. Tried to access my-team-claude-sonnet-5",
        "type": "key_model_access_denied",
        "param": "model",
        "code": "403"
    }
}

The message lists the models your key can use. Switch to one of those, or ask your instructor or ai-verde-support@cyverse.org to add the model to your course or team. You may also see team_model_access_denied or user_model_access_denied, which mean the same thing at the team or user level.

429 Too Many Requests¶

A 429 has two very different causes. Read the message before you retry.

Budget exceeded¶

Your course, team, or key has spent its budget:

{
    "error": {
        "message": "Budget has been exceeded! Team=team-example Current cost: 10.5, Max budget: 10.0",
        "type": "budget_exceeded",
        "param": null,
        "code": "429"
    }
}

Look for type: "budget_exceeded" or Budget has been exceeded in the message. Retrying won't work. Requests resume after the budget resets or after CyVerse staff raise it. Instructors can't change budgets themselves, so email ai-verde-support@cyverse.org and include the course or team name.

Model busy or temporarily unavailable¶

If the message says No deployments available or No healthy deployment available, AI-VERDE has no capacity for that model right now. Messages containing litellm.RateLimitError mean the provider is throttling requests.

These clear up on their own. If the response includes a Retry-After header or says Try again in <seconds> seconds, wait that long before retrying. Otherwise, wait a little longer between each retry, or switch to another model from your list for now. If the error lasts more than an hour or so, email support.

404 Not Found: wrong URL¶

A request to a URL that AI-VERDE doesn't serve returns this instead of the usual error object:

{
    "detail": "Not Found"
}

Almost always the base URL is wrong for the client you're using. Check it against this table:

OpenAI-compatible clients add /chat/completions to the base URL themselves, so don't include it. A base URL that ends in /v1/v1 or is missing /v1 both produce 404. See Base URL and Authentication for details.

A 405 Method Not Allowed means the path exists but the client used the wrong HTTP method, for example GET on /v1/chat/completions instead of POST.

500 and 503: provider problems¶

These errors mean AI-VERDE received your request but couldn't reach the model provider.

There's nothing to change on your side. Wait a few minutes and retry. If the error persists, email ai-verde-support@cyverse.org with the model name, the time, and the full message.

Errors in Python code¶

Python libraries turn these HTTP errors into exceptions. The exception name tells you which section above applies.

The OpenAI SDK raises exceptions by HTTP status, such as AuthenticationError for 401, PermissionDeniedError for 403, NotFoundError for 404, and RateLimitError for 429. A budget error and a busy-model error both raise RateLimitError, so check the exception message for budget_exceeded before retrying in a loop.

LangChain and LlamaIndex use LiteLLM under the hood, so you may see LiteLLM exception names:

Contacting support¶

If none of the above fixes the problem, email ai-verde-support@cyverse.org with:

• the full error message, including the HTTP status
• the model name you requested
• the tool or library you're using and its base URL
• roughly when the error happened

Don't include your API key in the email.