Antbase/Documentation

Troubleshooting

Common issues and how to resolve them when integrating with ANT.

Connection Issues

Cannot reach ANT / connection refused

  • Verify you can reach the API: curl -s https://antbase.ai/healthz
  • Check your base URL includes /v1 for OpenAI SDK clients
  • For Anthropic SDK, use https://antbase.ai without /v1
  • Make sure your firewall or proxy isn't blocking outbound HTTPS

Timeout errors

  • Complex prompts or large context windows may take longer — increase your client timeout
  • Try ant:fast for quicker responses
  • Free models may have higher latency — use ant:auto or ant:best for paid, lower-latency routing

Authentication

401 Unauthorized

  • API keys start with ant_ — verify your key format
  • Check the Authorization: Bearer YOUR_KEY header is set correctly
  • The key may have been revoked — check the API Keys page in your dashboard
  • For OpenClaw, check ~/.openclaw/openclaw.json has the correct apiKey value

402 Insufficient Credits

  • Your workspace balance is too low — top up credits in the dashboard
  • Use ant:free for zero-cost requests while testing
  • New accounts start with $5 free credits

Routing & Models

Model not found / INVALID_MODEL

  • Use virtual model names: ant:auto, ant:best, ant:fast, ant:free
  • For direct model access, use the full model ID (e.g., anthropic/claude-sonnet-4-6)
  • Check available models: curl -s https://antbase.ai/v1/models -H "Authorization: Bearer YOUR_KEY"

Wrong model selected / unexpected routing

  • Check the X-Antbase-Model response header to see which model was used
  • Use ant:best to force premium models for complex tasks
  • Adjust speed/quality/cost weights in your dashboard preferences
  • Create a custom nest to restrict routing to specific models

502 PROVIDER_ERROR / 503 ALL_PROVIDERS_DOWN

  • ANT automatically retries with different providers — if all fail, the error is returned
  • Check https://antbase.ai/healthz for system status
  • This is usually a temporary upstream provider issue — retry after a few seconds
  • If persistent, check the dashboard for provider health status

Integration-Specific

OpenClaw: "provider not found"

  • Ensure "defaultProvider": "antbase" is set in ~/.openclaw/openclaw.json
  • Or use -p antbase flag to select the provider explicitly
  • Run the installer again: curl -fsSL https://antbase.ai/install.sh | bash

OpenCode / Kilo: not using ANT

  • Verify the environment variables are set: echo $OPENAI_API_BASE
  • Some editors need to be restarted after changing environment variables
  • Check the tool's settings/config to confirm the base URL and API key

iOS / Mobile: image requests fail

  • Use ant:best for vision requests — it routes to models with vision support
  • Images must be base64-encoded as data:image/jpeg;base64,...
  • Compress images before sending — JPEG at 0.7-0.8 quality is usually sufficient
  • Maximum image size depends on the routed model's context window

Streaming

Streaming not working

  • Set "stream": true in your request body
  • Response format is Server-Sent Events (SSE) — parse data: ... lines
  • The stream ends with data: [DONE]
  • Make sure your HTTP client supports streaming (not all do by default)

Quick Diagnostic

Run these commands to verify your setup:

# 1. Check ANT is reachable
curl -s https://antbase.ai/healthz

# 2. Verify your API key works
curl -s https://antbase.ai/v1/models \
  -H "Authorization: Bearer YOUR_ANT_API_KEY" | head -c 200

# 3. Test a simple request
curl -s -X POST https://antbase.ai/v1/chat/completions \
  -H "Authorization: Bearer YOUR_ANT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"ant:auto","messages":[{"role":"user","content":"ping"}],"max_tokens":10}'

# 4. Check response headers
curl -s -D - -o /dev/null -X POST https://antbase.ai/v1/chat/completions \
  -H "Authorization: Bearer YOUR_ANT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"ant:auto","messages":[{"role":"user","content":"ping"}],"max_tokens":10}' \
  2>&1 | grep -i x-antbase

Still stuck? Check your dashboard at antbase.ai/app for request logs and error details. Every request is traced with full pipeline information.