Rollgate
Sign inSign up

Error Codes & Troubleshooting

Complete reference of API error codes and solutions to common problems.

Error Response Format

All API errors return a consistent JSON structure:

{
  "error": {
    "code": "AUTH_004",
    "category": "AUTH",
    "message": "Invalid API key",
    "details": "The provided API key has been revoked",  // optional
    "field": "authorization",                            // optional
    "retryable": false
  }
}

Authentication Errors

AUTH_001401Authentication required

No valid authentication was provided. The request is missing an Authorization header or session cookie.

Solution: Include your API key in the Authorization header: 'Authorization: Bearer your_api_key'. For dashboard endpoints, ensure you are logged in.

AUTH_002401Invalid authentication token

The authentication token provided is malformed or not recognized.

Solution: Check the token format. If using JWT, ensure it hasn't been corrupted. Generate a new token if needed.

AUTH_003401Token expired

The authentication token has expired and is no longer valid.

Solution: Refresh your session or generate a new API key from Settings.

AUTH_004401Invalid API key

The API key provided in the Authorization header is invalid, expired, or has been revoked.

Solution: Check that you're using the correct API key. Generate a new key from Settings if needed.

AUTH_005401API key expired

The API key has passed its expiration date.

Solution: Generate a new API key from Settings. Consider setting a longer expiration or no expiration for production keys.

AUTH_006403Insufficient permissions

The authenticated user or API key doesn't have permission for this operation. Client keys are read-only.

Solution: Use a server API key for write operations (create, update, delete). Ensure your user role has the required permissions.

AUTH_007401Session expired

The user session has expired. This typically occurs in the dashboard after a period of inactivity.

Solution: Log in again to refresh your session.

Validation Errors

VAL_001400Invalid request

The request body is malformed, contains invalid JSON, or has invalid field values.

Solution: Ensure your request body is valid JSON. Check for missing quotes, trailing commas, or encoding issues.

VAL_002400Missing required field

A required field is missing from the request. The 'field' property in the error indicates which field.

Solution: Check the API documentation for required fields. The 'field' property in the error response tells you which field is missing.

VAL_003400Invalid field format

A field value doesn't match the expected format (e.g., invalid email, wrong date format).

Solution: Check the expected format for the field. The 'details' property provides specific format requirements.

VAL_004400Invalid field value

A field value is syntactically correct but semantically invalid (e.g., percentage > 100).

Solution: Review the field constraints. Common issues: rollout percentage outside 0-100, invalid enum values.

VAL_009400Invalid flag key

Flag keys must start with a letter and contain only lowercase letters, numbers, underscores, and hyphens.

Solution: Use a valid flag key format, e.g., 'new_feature', 'beta-mode', 'checkout2'. Avoid spaces and special characters.

VAL_010400Invalid slug

Slugs must contain only lowercase letters, numbers, and hyphens.

Solution: Use a valid slug format, e.g., 'my-project', 'staging-env'. Avoid spaces and special characters.

Resource Errors

NOT_FOUND_001404Resource not found

The requested resource doesn't exist or you don't have access to it.

Solution: Verify the resource ID is correct. Check that you're using the right organization/project/environment context.

NOT_FOUND_002404Organization not found

The specified organization doesn't exist or you are not a member.

Solution: Check the organization ID or slug. Ensure you have been invited to the organization.

NOT_FOUND_003404Project not found

The specified project doesn't exist within the organization.

Solution: Verify the project ID or slug. Ensure the project exists in the correct organization.

NOT_FOUND_004404Environment not found

The specified environment doesn't exist within the project.

Solution: Verify the environment ID. Check that the environment was created in the correct project.

NOT_FOUND_005404Feature flag not found

The specified feature flag doesn't exist within the project.

Solution: Verify the flag key or ID. Note that flag keys are case-sensitive and project-scoped.

NOT_FOUND_006404User not found

The specified user doesn't exist or has been deleted.

Solution: Verify the user ID or email. The user may have deleted their account.

NOT_FOUND_007404API key not found

The specified API key doesn't exist or has been deleted.

Solution: Verify the API key ID. The key may have been revoked by an administrator.

Conflict Errors

CONFLICT_001409Resource conflict

A resource with the same identifier already exists.

Solution: Use a different identifier. Check the 'details' field for more information about the conflict.

CONFLICT_002409Email already registered

An account with this email address already exists.

Solution: Use a different email address or log in with the existing account.

CONFLICT_003409Organization slug taken

An organization with this slug already exists.

Solution: Choose a different slug for your organization.

CONFLICT_004409Project slug taken

A project with this slug already exists in the organization.

Solution: Choose a different slug for your project within this organization.

CONFLICT_006409Flag key taken

A flag with this key already exists in the project.

Solution: Use a different flag key. Each key must be unique within a project.

Rate Limiting

RATE_001429Rate limit exceeded

You've exceeded the rate limit for this endpoint. Limits vary by endpoint type and plan.

Solution: Wait for the time specified in the Retry-After header. Consider implementing caching or request batching.

RATE_003429Monthly quota exceeded

You've exceeded your plan's monthly API request quota.

Solution: Upgrade your plan or wait for the next billing cycle. Current usage is shown in Settings.

Rate Limit Headers

Rate-limited responses include headers to help you manage your request rate:

X-RateLimit-LimitMaximum requests allowed in the window
X-RateLimit-RemainingRequests remaining in current window
X-RateLimit-ResetUnix timestamp when the window resets
Retry-AfterSeconds to wait before retrying
Endpoint TypeLimitWindow
SDK endpoints (/sdk/*)1,000per minute per API key
Auth endpoints (/auth/*)10per minute per IP
Dashboard endpoints100per minute per user

Server Errors

INTERNAL_001500Internal server error

An unexpected error occurred on the server. These are automatically logged and investigated.

Solution: Retry the request (this error is retryable). If the problem persists, check status.rollgate.io or contact support.

INTERNAL_002500Database error

A database operation failed. This is typically a transient issue.

Solution: Retry the request. If the problem persists, the service may be experiencing issues.

INTERNAL_003500Cache error

A cache operation failed. The request may still succeed on retry.

Solution: Retry the request. Cache errors are usually transient.

INTERNAL_004503Service unavailable

The service is temporarily unavailable due to maintenance or high load.

Solution: Wait and retry. Check status.rollgate.io for maintenance announcements.

Troubleshooting Guide

Common problems and step-by-step solutions.

Flags always return false

Possible Causes
  • • Flag is disabled in the current environment
  • • Global rollout is set to 0%
  • • User attributes don't match any targeting rules
  • • Using the wrong environment API key
Solutions
  • 1. Check the flag is enabled in the dashboard for your environment
  • 2. Verify the rollout percentage is > 0% or targeting rules are configured
  • 3. Use the Playground to test with specific user attributes
  • 4. Confirm you're using an API key from the correct environment

SSE connection keeps disconnecting

Possible Causes
  • • Network instability or proxy timeouts
  • • Server-side connection limit reached
  • • Client not handling reconnection properly
Solutions
  • 1. Implement exponential backoff for reconnection (SDK does this automatically)
  • 2. Check your SSE connection count in Settings
  • 3. Ensure your proxy/load balancer supports long-lived connections
  • 4. Consider using polling as a fallback for unstable networks

Flag changes not reflecting immediately

Possible Causes
  • • SDK cache not invalidated
  • • SSE connection not established
  • • CDN caching the response
Solutions
  • 1. Call sdk.refresh() to force a cache refresh
  • 2. Verify SSE is connected (SDK emits "connected" event)
  • 3. Check that you're not using an HTTP cache proxy that ignores Cache-Control
  • 4. SDK flags refresh automatically within 1 second via SSE

Getting 401 errors after key rotation

Possible Causes
  • • Old API key cached in environment variables
  • • Deployment not picking up new key
  • • Multiple services using the old key
Solutions
  • 1. Restart your application to reload environment variables
  • 2. Verify the new key is correctly set in your deployment config
  • 3. Check all services that use the API key and update them
  • 4. Use the key prefix in the dashboard to identify which key is being used

Targeting rules not working as expected

Possible Causes
  • • User attributes not being sent correctly
  • • Attribute name mismatch (case-sensitive)
  • • Rule evaluation order not understood
Solutions
  • 1. Log the user context being sent to verify attributes
  • 2. Ensure attribute names match exactly (country vs Country)
  • 3. Remember: rules are evaluated top-to-bottom, first match wins
  • 4. Use the Playground to test rule evaluation with specific attributes

High latency on flag evaluation

Possible Causes
  • • Not using SDK caching
  • • Making API calls on every page load
  • • Network latency to API server
Solutions
  • 1. Use the official SDK which caches flags locally
  • 2. Initialize the SDK once at app startup, not per-request
  • 3. Enable SSE for real-time updates instead of polling
  • 4. For edge locations, consider using a CDN or regional deployment

Debug Mode

Enable debug mode in the SDK to get detailed logs about flag evaluation:

// Node.js
const client = new RollgateClient({
  apiKey: 'your_key',
  debug: true  // Logs evaluation details to console
});

// React
<RollgateProvider apiKey="your_key" debug>
  <App />
</RollgateProvider>

Debug mode logs: cache hits/misses, SSE events, rule evaluation steps, and API calls.

Getting Help

GitHub Discussions

Ask questions and discuss with the community

API Reference

Interactive OpenAPI documentation