Authentication Errors

Errors related to API authentication and authorization.

Error Codes

Code	HTTP Status	Description
invalid_api_key	401	API key is invalid or malformed
expired_api_key	401	API key has expired
revoked_api_key	401	API key has been revoked
missing_api_key	401	No API key provided
insufficient_permissions	403	API key lacks required permissions
invalid_organization	403	Organization mismatch or invalid
suspended_account	403	Account has been suspended
quota_exceeded	403	Usage quota has been exceeded

Error Format

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "The API key provided is invalid.",
    "param": null,
    "doc_url": "https://docs.gateflow.ai/api-reference/errors/auth-errors#invalid_api_key"
  }
}

Error Details

invalid_api_key

The API key format is incorrect or the key doesn't exist.

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "The API key provided is invalid. Please check your API key and try again."
  }
}

Common causes:

• Typo in the API key
• Using a key from a different environment (dev vs prod)
• Key was deleted
• Incorrect key format (should start with gw_)

Resolution:

1. Verify the API key in your GateFlow dashboard
2. Ensure you're using the correct environment
3. Generate a new key if needed

expired_api_key

The API key has passed its expiration date.

{
  "error": {
    "type": "authentication_error",
    "code": "expired_api_key",
    "message": "The API key has expired. Please generate a new key.",
    "expired_at": "2026-02-01T00:00:00Z"
  }
}

Resolution:

1. Go to the API Keys section in your dashboard
2. Generate a new API key
3. Update your application configuration

revoked_api_key

The API key has been manually revoked.

{
  "error": {
    "type": "authentication_error",
    "code": "revoked_api_key",
    "message": "This API key has been revoked.",
    "revoked_at": "2026-02-15T10:00:00Z"
  }
}

Resolution:

1. Contact your organization admin
2. Generate a new API key if authorized

missing_api_key

No API key was provided in the request.

{
  "error": {
    "type": "authentication_error",
    "code": "missing_api_key",
    "message": "No API key provided. Include your API key in the Authorization header."
  }
}

Resolution: Add the Authorization header to your request:

curl https://api.gateflow.ai/v1/chat/completions \
  -H "Authorization: Bearer gw_prod_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-5.2", "messages": [{"role": "user", "content": "Hello"}]}'

insufficient_permissions

The API key doesn't have permission for the requested operation.

{
  "error": {
    "type": "authentication_error",
    "code": "insufficient_permissions",
    "message": "Your API key does not have permission to access audio endpoints.",
    "required_permission": "audio",
    "current_permissions": ["chat", "embeddings"]
  }
}

Resolution:

1. Check the key's permissions in your dashboard
2. Use a different key with the required permissions
3. Request permission changes from your admin

invalid_organization

The organization ID doesn't match the API key.

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_organization",
    "message": "The specified organization does not match your API key."
  }
}

Resolution:

1. Remove the organization header if not needed
2. Verify the organization ID is correct
3. Use an API key associated with the target organization

suspended_account

The account associated with the API key has been suspended.

{
  "error": {
    "type": "authentication_error",
    "code": "suspended_account",
    "message": "Your account has been suspended. Please contact support.",
    "reason": "payment_overdue",
    "support_url": "https://gateflow.ai/support"
  }
}

Common reasons:

• Payment issues
• Terms of service violation
• Suspicious activity

Resolution: Contact GateFlow support to resolve the suspension.

quota_exceeded

The usage quota for the API key or account has been exceeded.

{
  "error": {
    "type": "authentication_error",
    "code": "quota_exceeded",
    "message": "Monthly usage quota exceeded.",
    "quota_type": "monthly_cost",
    "limit": 1000.00,
    "current": 1000.50,
    "resets_at": "2026-03-01T00:00:00Z"
  }
}

Resolution:

1. Wait for the quota to reset
2. Upgrade your plan for higher limits
3. Contact admin to increase the quota

Handling Auth Errors

Python

import openai

client = openai.OpenAI(
    base_url="https://api.gateflow.ai/v1",
    api_key="gw_prod_..."
)

try:
    response = client.chat.completions.create(
        model="gpt-5.2",
        messages=[{"role": "user", "content": "Hello"}]
    )
except openai.AuthenticationError as e:
    error = e.body.get("error", {})
    code = error.get("code")

    if code == "invalid_api_key":
        print("Please check your API key")
    elif code == "expired_api_key":
        print("API key expired, please generate a new one")
    elif code == "insufficient_permissions":
        print(f"Missing permission: {error.get('required_permission')}")
    else:
        print(f"Auth error: {error.get('message')}")

JavaScript/TypeScript

import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://api.gateflow.ai/v1',
  apiKey: 'gw_prod_...',
});

try {
  const response = await client.chat.completions.create({
    model: 'gpt-5.2',
    messages: [{ role: 'user', content: 'Hello' }],
  });
} catch (error) {
  if (error instanceof OpenAI.AuthenticationError) {
    const code = error.error?.code;

    switch (code) {
      case 'invalid_api_key':
        console.error('Please check your API key');
        break;
      case 'expired_api_key':
        console.error('API key expired');
        break;
      case 'insufficient_permissions':
        console.error('Missing required permissions');
        break;
      default:
        console.error('Authentication error:', error.message);
    }
  }
}

Best Practices

1. Secure key storage - Never commit API keys to source control
2. Use environment variables - Store keys in environment variables
3. Rotate keys regularly - Use the key rotation feature
4. Minimum permissions - Only grant permissions that are needed
5. Monitor usage - Set up alerts for unusual activity

See Also

• API Key Management - Key management guide
• Key Rotation - Rotation best practices
• Error Overview - General error handling