Use RutaAPI with Claude Code

Before you start

You need a RutaAPI account, a prepaid credit pack, and an API key. Make sure your account has credits before making requests — requests without sufficient credits will return a 401 or 403 error.

How to start with RutaAPI

curl https://api.rutaapi.com/v1/models \
  -H "Authorization: Bearer YOUR_RUTAAPI_KEY"

export ANTHROPIC_BASE_URL="https://api.rutaapi.com"
export ANTHROPIC_AUTH_TOKEN="YOUR_RUTAAPI_KEY"
export ANTHROPIC_MODEL="MODEL_NAME"

curl https://api.rutaapi.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_RUTAAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_NAME",
    "messages": [
      {"role": "user", "content": "Hello from RutaAPI"}
    ]
  }'

Who this guide is for

This guide is for Claude Code users who want to connect Claude Code to an OpenAI-compatible API gateway provided by RutaAPI.

It helps if you are familiar with environment variables, API keys and making HTTP requests from a terminal.

Who should not use this setup

• Users whose Claude Code version does not support custom Base URL configuration.
• Users who require official Anthropic or Claude Code-only features.
• Users whose tool does not support custom API endpoints.

Testing before you start coding

Before running any Claude Code coding tasks, send a simple request from the terminal to confirm your key, Base URL and model name all work together. This rules out configuration issues before you start a real session.

If the first request succeeds, the Claude Code configuration should also work. If it fails, fix the terminal request first — that gives you clearer error messages than the Claude Code CLI.

How to pick a model name

Model names are returned by the GET /v1/models endpoint. Copy one of the model id values from the response and use it as the model name in your Claude Code environment configuration.

Model availability is per-account. If a model name is not in your /v1/models response, it is not active in your account — add more credits or contact support.

Common mistakes

• Using https://rutaapi.com as the Base URL instead of https://api.rutaapi.com.
• Using https://app.rutaapi.com as the Base URL.
• Using https://api.rutaapi.com/v1/chat/completions as the Base URL — that is an endpoint, not the root.
• Mixing a RutaAPI key with another provider's Base URL.
• Guessing the model name instead of copying from /v1/models.
• Using an expired or disabled key.
• Not having enough credits.
• Selecting a model that is not available in your account.
• Not sourcing the shell configuration after editing it.
• Setting variables in the wrong shell init file.

Common errors

401 Unauthorized / invalid API key

The API key is missing, incorrect, or sent to the wrong Base URL. Verify the key and Base URL both come from RutaAPI. Run /v1/models to confirm the key is valid.

403 Forbidden

The key exists but lacks permission. Check credits and model access in your RutaAPI account.

404 Model not found

The model name is not in your account. Run GET /v1/models and copy a returned model id.

429 Too Many Requests

Rate or concurrency limit. Lower the number of concurrent requests and retry.

503 Service Unavailable

The provider route is temporarily unavailable. Try a short request, check model availability, contact support if persistent.

524 Gateway Timeout

Proxy or gateway timeout — the upstream model did not respond in time. This is usually a timeout at the proxy or gateway layer, not an Anthropic error. Check request size, upstream availability and proxy settings.

When RutaAPI may be a good fit

• You need an OpenAI-compatible Base URL for Claude Code
• You want dashboard-generated API keys
• You want prepaid credits
• You want to verify available models with /v1/models
• You need docs for Claude Code, Codex CLI, Cursor, Cline and Continue.dev
• You want usage visibility before scaling

When RutaAPI may not be the right fit

• Your Claude Code version does not support the needed provider mode
• The selected model is unavailable upstream
• Your API key belongs to another provider
• You require official Anthropic or Claude Code-only features
• You need official Anthropic or Claude Code-only features instead of an API gateway

Related setup and troubleshooting guides

• API Key and Base URL explained
• Unified Base URL for AI coding tools
• Claude Code 524 / 503 timeout troubleshooting
• Codex CLI invalid_api_key troubleshooting
• Codex CLI setup with RutaAPI
• Cursor custom API setup guide
• Cline OpenAI-compatible API setup
• Continue.dev OpenAI-compatible API setup
• Available models
• Pricing and credit packs