API Key Authentication Errors

Common Error Messages

• "Invalid API key"
• "401 Unauthorized"
• "Authentication failed"
• "API key not found"
• "Incorrect API key provided"

OpenAI API Key Errors

Invalid API Key

Error: "Incorrect API key provided"

Solutions:

• Verify key starts with sk-
• Check for extra spaces or characters when copying
• Ensure key hasn't been revoked in OpenAI dashboard
• Try generating a new key

Quota Exceeded

Error: "You exceeded your current quota"

Solutions:

• Add payment method in OpenAI billing
• Increase usage limit in OpenAI settings
• Check if free credits have expired
• Wait for monthly quota reset

Rate Limit

Error: "Rate limit reached"

Solutions:

• OpenClaw automatically retries with backoff
• Reduce message volume if possible
• Upgrade to higher tier for more requests/minute

Anthropic API Key Errors

Invalid API Key

Error: "invalid x-api-key"

Solutions:

• Verify key starts with sk-ant-
• Check key is correctly set in ANTHROPIC_API_KEY
• Ensure no extra characters or spaces
• Generate new key from Anthropic console

Insufficient Credits

Error: "credit balance is too low"

Solutions:

• Add credits in Anthropic billing
• Set up auto-reload for credits
• Check current balance in console

General Troubleshooting Steps

1. Verify Environment Variable Name:
   • OpenAI: OPENAI_API_KEY (exactly)
   • Anthropic: ANTHROPIC_API_KEY
   • Case-sensitive!
2. Check Key Format:
   • OpenAI keys: start with sk-
   • Anthropic keys: start with sk-ant-
   • No spaces, quotes, or extra characters
3. Test Key Directly:
   • Make test API call using curl or provider dashboard
   • Verify key works outside of AgentClaw
4. Regenerate Key:
   • Create new key in provider dashboard
   • Update environment variable
   • Restart instance
   • Revoke old key if new one works

After Updating API Keys

Critical: Always restart your instance after updating API keys!

1. Save new API key in configuration
2. Click "Restart Instance"
3. Wait for instance to fully start
4. Check logs for successful provider connection
5. Test with a message

Security Best Practices

• Never share API keys: Treat them like passwords
• Use separate keys: Different keys for dev/prod
• Rotate regularly: Change keys every few months
• Revoke compromised keys: Immediately if exposed
• Monitor usage: Check for unexpected activity
• Set spending limits: Prevent surprise bills

Reading Logs for API Errors

To diagnose API key issues:

1. Go to instance Logs tab
2. Filter for ERROR level
3. Look for messages containing:
   • "authentication"
   • "API key"
   • "401"
   • "unauthorized"
4. Note which provider is mentioned
5. Check corresponding API key

Provider-Specific Resources

• Where to get OpenAI API keys
• Where to get Anthropic API keys
• Adding API keys securely
• Updating environment variables

Still Having Issues?

If problems persist after trying the above:

• Contact provider support to verify key status
• Email support@agentclaw.app with:
  • Instance name
  • Provider affected (OpenAI/Anthropic)
  • Screenshot of error from logs
  • Steps already tried

Next Steps

• Learn about troubleshooting startup failures
• Read about network and connection issues
• Understand reading logs