Error Handling & Troubleshooting

Common Error Responses

Invalid API Key

Occurs when the API key is invalid, inactive, or has been revoked.

{
  "success": false,
  "error": "invalid_api_key",
  "message": "Invalid or inactive API key"
}

HTTP Status: 401 Unauthorized

Solutions:

• Verify the API key is correct (no extra spaces or characters)
• Check if the key has been revoked in API Key Management
• Ensure you're using the full key including the gb_live_ prefix
• Create a new key if the old one was lost or compromised

Insufficient Scopes

Occurs when your API key doesn't have the required permissions for the endpoint.

{
  "success": false,
  "error": "insufficient_scopes",
  "message": "API key lacks required permissions for this endpoint"
}

HTTP Status: 403 Forbidden

Solutions:

• Check which scope is required for the endpoint (see Authentication & Scopes)
• Update your API key in API Key Management to include the required scope
• Create a new key with the necessary permissions if you can't modify the existing one

API Key Not Allowed (Write Operation)

Occurs when attempting to use an API key on a write endpoint.

{
  "success": false,
  "error": "api_key_not_allowed",
  "message": "API keys are read-only and cannot be used on write endpoints. Use session-based authentication for write operations."
}

HTTP Status: 403 Forbidden

Solutions:

• API keys are read-only - they cannot be used for write operations
• For write operations, use session-based authentication through the web interface
• Review the endpoint documentation to confirm it's read-only

IP Not Allowed

Occurs when your IP address is not whitelisted for the API key.

{
  "success": false,
  "error": "ip_not_allowed",
  "message": "IP address not allowed for this API key"
}

HTTP Status: 403 Forbidden

Solutions:

• Check your current IP address
• Verify the IP restrictions in API Key Management
• Add your IP address to the whitelist or remove IP restrictions if appropriate
• If using a dynamic IP, consider removing IP restrictions or using a VPN with a static IP

API Key Expired

Occurs when the API key has passed its expiration date.

{
  "success": false,
  "error": "api_key_expired",
  "message": "API key has expired"
}

HTTP Status: 401 Unauthorized

Solutions:

• Check the expiration date in API Key Management
• Create a new API key
• Update your integration to use the new key
• Consider setting a longer expiration or removing expiration for long-term integrations

Rate Limiting

API keys are subject to rate limiting. Check response headers for rate limit information:

• X-RateLimit-Limit: Maximum requests allowed
• X-RateLimit-Remaining: Remaining requests in current window
• X-RateLimit-Reset: Time when the rate limit resets

If you hit rate limits:

• Wait for the rate limit window to reset
• Implement exponential backoff in your integration
• Reduce request frequency if possible
• Contact support if you need higher rate limits

Troubleshooting Checklist

1. Verify API Key Format
   • Key should start with gb_live_
   • No extra spaces or line breaks
   • Full key is included in the Authorization header
2. Check Key Status
   • Key is active (not revoked)
   • Key hasn't expired
   • Key exists in API Key Management
3. Verify Scopes
   • Key has the required scope for the endpoint
   • Scopes are correctly configured
4. Check IP Restrictions
   • Your IP address is whitelisted (if restrictions are set)
   • IP restrictions allow your current location
5. Verify Endpoint
   • Endpoint URL is correct
   • Using GET method (API keys are read-only)
   • Query parameters are properly formatted
6. Check Network
   • No firewall blocking requests
   • Network connectivity is stable
   • SSL/TLS certificates are valid

Testing Your API Key

Use the provided test script to verify your API key:

./test-readonly-endpoints.sh your_api_key

Or with environment variable:

API_KEY=your_api_key ./test-readonly-endpoints.sh

Getting Help

If you continue to experience issues:

• Check API key status in the web interface
• Verify scopes are correctly configured
• Ensure IP restrictions allow your IP address
• Review the Best Practices & Security guide
• Contact support if you need write access (requires session authentication)