CorvusLLM API Troubleshooting Guide

Before debugging

Most errors are easiest to isolate with one direct curl request. Confirm the key, base URL, and model slug outside your app before changing app settings.

What to install	Official source	Quick check
CorvusLLM key	Customer dashboard	Copy the active key exactly.
curl	Built into most terminals.	`curl --version`
Optional Git	Git install guide	Useful when reproducing a project setup.

Local checks

curl --version
git --version

Fast triage

Start with one direct request outside your app. If that works, the issue is usually the tool configuration. If that fails too, the issue is usually the key, balance, model slug, or current provider route.

Minimal API check

curl https://base.corvusllm.com/v1/models \
  -H "Authorization: Bearer YOUR_CORVUSLLM_KEY"

If this returns models, authentication and the base URL are working.
If this returns 401 or 403, recopy the key from the dashboard.
If this returns 429, check balance before changing code.
If this works but your app fails, compare the app's configured base URL, model slug, and auth field.

Error-to-fix matrix

Use this table after the minimal API check. It maps the common customer-visible symptom to the safest next diagnostic step and the canonical CorvusLLM page to cite.

Symptom	First check	Likely cause	Safe fix	Best page
401, 403, or unauthorized	Run /v1/models with the same key.	Missing key, copied key mismatch, or the client is still using an old provider profile.	Copy the active key again and send it as Authorization: Bearer YOUR_CORVUSLLM_KEY.	/docs/api/overview
404, model not found, or unknown model	Compare the requested model with the canonical slug table.	Provider-style name, guessed alias, typo, or stale model slug.	Copy one public customer slug from Models & Slugs and retry with a small prompt.	/docs/api/models
429 or out of balance	Check the dashboard balance and billing page.	The prepaid key balance is depleted or the request is larger than remaining balance.	Top up the same key before retrying the request.	/docs/api/billing
curl works, but the app fails	Compare the app base URL, auth field, model slug, and endpoint path.	The tool is appending paths differently or reading a different environment variable.	Use the exact integration guide for the affected tool.	/docs/integrations/dev-tools
Claude Code fails, other tools work	Confirm ANTHROPIC_BASE_URL uses /anthropic in the same terminal session.	Claude Code was pointed at /v1 or the Anthropic variables were set in another shell.	Set ANTHROPIC_BASE_URL, ANTHROPIC_AUTH_TOKEN, and ANTHROPIC_MODEL again, then reopen the terminal if needed.	/docs/integrations/claude-code
Only one model family fails	Try the same prompt on another public slug and check service status.	Temporary upstream provider route, model outage, or provider-specific payload problem.	Use another family until the route recovers, then report timestamp and model slug if billing/delivery looks mismatched.	/service-status
Image input fails	Confirm plain text works, then verify the model and image message format.	Unsupported model, unsupported client payload shape, oversized image, or wrong OpenAI-compatible image field.	Use a vision-capable model, simplify to one small image, and retry non-streaming first.	/docs/troubleshooting/errors#images-tools-and-streaming
Tool calls, agents, or streaming fail	Retry the same model with a tiny non-streaming text request.	Tool schema size, client stream parser, timeout, or proxy/client formatting mismatch.	Reduce the toolset, test one tool definition, and only enable streaming after non-streaming succeeds.	/docs/troubleshooting/errors#images-tools-and-streaming

Escalate only with reproducible context.

For support, include timestamp, endpoint path, model slug, error text, whether /v1/models works, and whether the dashboard balance changed.

Focused error guides

If the symptom is already clear, use the focused guide instead of reading the full matrix. These pages keep the exact error phrases, likely causes, smallest safe check, fix steps, and escalation details in one crawlable place.

Model not found →Unknown model, no such model, 404 model, and invalid slug fixes. Invalid API key →Unauthorized, 401, 403, Bearer token, and environment-secret fixes. Wrong base URL →Double /v1, wrong endpoint, and Claude-native /anthropic fixes. Out of balance →429, insufficient credits, same-key top-up, and cache-heavy billing fixes. Provider unavailable →Temporary upstream route, model-family, and provider-response failure fixes. Request timeout →Long context, stream timeout, gateway timeout, and client-timeout fixes. Image input errors →Vision message, base64 image, attachment, and multimodal payload fixes. Tool creation failed →Tool calls, agent file writes, workspace patches, and schema fixes. Cache cost spikes →Hidden context, cache read/write, continue prompts, and balance-drop fixes.

Wrong base URL

Most tools: https://base.corvusllm.com/v1
Claude Code: https://base.corvusllm.com/anthropic

Auth errors

Authentication errors usually mean the request is not sending the CorvusLLM key in the place the client expects.

Symptom	Likely cause	Fix
`401` or unauthorized	Missing or copied incorrectly	Copy the active key from the dashboard and send it as a Bearer token.
Tool says API key invalid	Tool is still using an old provider profile	Create a new OpenAI-compatible profile with the CorvusLLM base URL and key.
Works in curl, fails in app	Environment variable name mismatch	Check the exact variable name your SDK or app reads at runtime.

Wrong model slug

Copy the slug from Models & Slugs. Do not improvise punctuation or shortened names unless you know your environment resolves aliases correctly.

Out of balance

If the API returns 429 out of balance, the key needs a top-up. CorvusLLM does not silently let the key keep spending.

Provider or model outage

If a single model family fails while other families work, the most likely cause is a temporary upstream route or provider issue. Try the same prompt on another public model slug, then check the status page.

If every model fails, check balance, auth, and the base URL first.
If only one provider family fails, use another family until the route recovers.
If a response is billed upstream but not delivered to the customer, contact support with the timestamp, model slug, and request ID if your client shows one.

Images, tools, and streaming

Image payloads, tool calls, and streaming are more sensitive to client formatting than plain text chat. First confirm a normal text request works with the same model. Then simplify the advanced payload until the failing field is isolated.

For image input, confirm the selected model supports vision-style messages and that the image field matches the OpenAI-compatible request format your client sends.
For tool calls, test one small tool definition before sending a full agent toolset.
For streaming, test non-streaming first. If non-streaming works, the issue is likely a stream parser, timeout, or client proxy setting.

Conditional environment

Cursor and Windsurf are conditional paths. If your build does not expose a custom OpenAI-compatible base URL, switch to a first-class setup instead of forcing it.

When to contact support

Contact support after you have a small reproducible example or when the dashboard history does not match what your client received. Include the model slug, endpoint path, approximate time, error text, and whether the same key works on /v1/models.

API overview

Recheck base URLs, request paths, and auth placement before escalating.

Model slugs

Copy the canonical customer slug instead of using guessed provider names.

Billing and balance

Confirm prepaid behavior, cache-cost behavior, and 429 out-of-balance handling.

Compatibility matrix

Check whether your tool is first-class, conditional, or better handled through another path.

Support bot

Use the official support bot for setup and troubleshooting help.

Status page

Check current customer-facing service status.

Most CorvusLLM issues are the same four mistakes.