Errors

Error format

All error responses return a JSON object with an error field:

{
  "error": "Error message"
}

Status codes

401 Unauthorized

Returned when the Authorization header is missing, malformed, or contains an invalid API key.

# Missing header
curl https://api.switchflag.dev/v1/flags
# → 401 {"error": "Unauthorized"}

# Invalid key
curl -H "Authorization: Bearer invalid_key" \
  https://api.switchflag.dev/v1/flags
# → 401 {"error": "Unauthorized"}

To fix: ensure you're sending Authorization: Bearer sf_... with a valid API key from your environment settings.

404 Flag not found

Returned by GET /v1/flags/{key} when the flag key doesn't exist in the project.

curl -H "Authorization: Bearer sf_production_..." \
  https://api.switchflag.dev/v1/flags/nonexistent-flag
# → 404 {"error": "Flag not found"}

Note: the SDK handles this gracefully by returning { value: undefined, reason: 'not_found' }.

429 Too many requests

Returned when the rate limit is exceeded. Check the Retry-After header for how long to wait.

# → 429 {"error": "Too many requests"}
# Headers:
#   Retry-After: 2
#   X-RateLimit-Limit: 100
#   X-RateLimit-Remaining: 0