Kill switch

The kill switch provides immediate, manual control to disable a specific provider or model. When activated, the gateway blocks all requests to the disabled entry — no traffic reaches the provider, and the fallback chain skips the entry automatically. The kill switch is designed for emergency response: a provider security incident, a model producing harmful output, or an operational issue that requires instant traffic cutoff.

---

What happens when the kill switch is activated

1. All requests targeting the disabled provider or model are blocked immediately with a 503 provider_unavailable error
2. Fallback chains skip the disabled entry — if gpt-4o is kill-switched and a fallback chain lists it as a secondary entry, the gateway proceeds to the next entry in the chain
3. The kill switch state is persisted to the database (kill_switch_disabled_at timestamp on the model config) and survives gateway restarts
4. The audit log records the activation with the identity of the admin who triggered it, the reason, and a timestamp

The kill switch does not affect requests already in flight. Requests that have been forwarded to the provider before the switch is activated complete normally.

---

Disabling a provider (all models)

Disable all models for a provider in a single call:

POST https://api.arbitex.ai/api/v1/admin/kill-switch/providers/openai/disable
Authorization: Bearer arb_live_your-api-key-here
Content-Type: application/json

{
  "reason": "maintenance"
}

Field	Required	Description
reason	Yes	One of: maintenance, cost_runaway, security_event, other

Response 200 OK:

{
  "provider": "openai",
  "total_models": 4,
  "kill_switch_disabled_count": 4,
  "kill_switch_active": true,
  "models": [
    {
      "id": "550e8400-...",
      "provider": "openai",
      "model_id": "gpt-4o",
      "display_name": "GPT-4o",
      "is_active": false,
      "kill_switch_active": true,
      "kill_switch_disabled_at": "2026-03-15T10:00:00Z",
      "disabled_reason": "maintenance"
    }
  ]
}

---

Disabling a single model

Disable a specific model by its model_config_id (UUID primary key, not the model ID string):

POST https://api.arbitex.ai/api/v1/admin/kill-switch/models/550e8400-e29b-41d4-a716-446655440000/disable
Authorization: Bearer arb_live_your-api-key-here
Content-Type: application/json

{
  "reason": "security_event"
}

Response 200 OK:

{
  "id": "550e8400-...",
  "provider": "openai",
  "model_id": "gpt-4o",
  "display_name": "GPT-4o",
  "is_active": false,
  "kill_switch_active": true,
  "kill_switch_disabled_at": "2026-03-15T10:00:00Z",
  "disabled_reason": "security_event"
}

Note

The model_config_id is the UUID primary key from the model_configs table, not the provider’s model ID string (e.g., gpt-4o). Use the list providers endpoint to look up config IDs.

---

Re-enabling a provider or model

Re-enable all models for a provider

POST https://api.arbitex.ai/api/v1/admin/kill-switch/providers/openai/enable
Authorization: Bearer arb_live_your-api-key-here

No request body required. Returns the updated ProviderKillSwitchSummary.

Re-enable a single model

POST https://api.arbitex.ai/api/v1/admin/kill-switch/models/550e8400-e29b-41d4-a716-446655440000/enable
Authorization: Bearer arb_live_your-api-key-here

No request body required. Returns the updated KillSwitchStateResponse.

Re-enabling restores the entry to normal operation. The health monitor state is evaluated independently — if the health monitor had previously disengaged the entry due to failures, re-enabling the kill switch does not override the health monitor state. The health monitor must independently verify the entry is healthy before routing live traffic.

---

Listing kill switch state

All providers

GET https://api.arbitex.ai/api/v1/admin/kill-switch/providers
Authorization: Bearer arb_live_your-api-key-here

Returns a list of ProviderKillSwitchSummary objects showing the kill switch state for every provider and their models.

Single model

GET https://api.arbitex.ai/api/v1/admin/kill-switch/models/{model_config_id}
Authorization: Bearer arb_live_your-api-key-here

Returns a KillSwitchStateResponse for a single model.

---

Disable reasons

Value	Use case
maintenance	Planned provider or model maintenance window
cost_runaway	Unexpected cost spike — disable until investigated
security_event	Provider security incident, model safety issue
other	Any other reason (document in your incident channel)

---

API endpoint summary

Method	Path	Description
GET	/api/v1/admin/kill-switch/providers	List all providers with kill switch state
POST	/api/v1/admin/kill-switch/providers/{provider}/disable	Disable all models for a provider
POST	/api/v1/admin/kill-switch/providers/{provider}/enable	Re-enable all models for a provider
GET	/api/v1/admin/kill-switch/models/{model_config_id}	Get kill switch state for a model
POST	/api/v1/admin/kill-switch/models/{model_config_id}/disable	Disable a single model
POST	/api/v1/admin/kill-switch/models/{model_config_id}/enable	Re-enable a single model

---

Fallback chain interaction

The kill switch overrides fallback chain configuration. When an entry is kill-switched:

• As a primary target: the gateway immediately falls through to the next entry in the fallback chain, as if the primary returned a 5xx error
• As a fallback entry: the gateway skips the kill-switched entry and continues to the next fallback in the chain
• As the only entry: the request returns 503 provider_unavailable with no further fallback attempts

Plan your fallback chains with the assumption that any single entry may be kill-switched at any time. A kill switch on a fallback chain entry does not generate an error — it is silently skipped.

---

Kill switch vs health monitoring

	Kill switch	Health monitor
Trigger	Manual — admin action	Automatic — based on failure thresholds
Scope	Provider-wide or single model	Individual model
Recovery	Manual — admin must re-enable	Automatic — test request after lockout period
Persistence	Survives restarts (database)	Resets on restart
Use case	Emergency response, planned maintenance	Transient provider failures

Both systems can be active simultaneously. If a model is both kill-switched and health-monitor-disengaged, re-enabling the kill switch does not restore traffic — the health monitor must also return to active state.

---

Emergency runbook

When you need to disable a provider immediately:

1. Activate the kill switch — use the provider-level disable endpoint to cut all traffic at once, or the model-level endpoint for a targeted disable. Include the appropriate reason.
2. Verify fallback chains are routing traffic to alternative providers. Check the audit log for 503 provider_unavailable errors — these indicate requests with no viable fallback.
3. Notify affected teams that the provider is disabled and which fallback providers are handling traffic.
4. Monitor the audit log for the disabled provider — the kill switch audit entry records the activation. Any subsequent requests to the disabled entry produce 503 audit entries.
5. When the incident is resolved, re-enable the provider via the enable endpoint. Monitor the health check endpoint to confirm the provider is healthy before re-enabling.

---

Audit log

Kill switch activations and deactivations produce audit log entries with:

Field	Description
action	kill_switch_disable or kill_switch_enable
provider	The affected provider
model_id	The affected model (or all models for provider-level switches)
user_id	The admin who triggered the switch
reason	The DisabledReason value provided at activation
timestamp	When the switch was toggled

These entries are forwarded to your SIEM alongside request audit entries.

---

See also

• Kill Switch API Reference — Full API schemas and response details
• Routing — Fallback chains, health monitoring, and provider management
• Audit Log — How kill switch events are recorded

---

Assessing blast radius before activation

Provider-wide kill switch

A provider-wide disable affects all models for that provider. Every request targeting any model on the provider falls through to the fallback chain.

Check before activating:

1. Which models are active on this provider? Go to Settings > Providers > [Provider] and review the model catalog entries.
2. Do all those models have fallback chains configured? Models without fallbacks will return 503 provider_unavailable to callers.
3. What is the current traffic volume? Check routing metrics before activating to establish a baseline.

Model-specific kill switch

A model-specific disable affects only that (provider, model) pair.

Check before activating:

1. Is this model used as a fallback for other models? A kill-switched fallback entry is silently skipped, removing a layer of redundancy. Check all fallback chain configurations that list this model.
2. Is this model the only option in any chain? If any chain has this model as its only entry with no further fallbacks, callers will receive 503 provider_unavailable after activation.

---

Multi-provider incident handling

For incidents involving multiple providers simultaneously (e.g., a shared infrastructure failure), activate kill switches in sequence:

# Disable provider 1
POST /api/v1/admin/kill-switch/providers/openai/disable
{ "reason": "security_event" }

# Disable provider 2
POST /api/v1/admin/kill-switch/providers/anthropic/disable
{ "reason": "security_event" }

Each activation produces its own audit entry. When recovering, re-enable in reverse order — re-enable the provider you are most confident about first, verify traffic, then re-enable the next.

---

Planned maintenance use case

For scheduled maintenance where you have advance notice, communicate with affected teams before activating and pre-configure fallback chains so callers experience no service disruption. Document the planned window in the reason string:

{
  "provider": "azure_openai",
  "enabled": false,
  "reason": "Planned maintenance window 2026-03-15 02:00–04:00 UTC — INC-5678"
}

---

Post-incident verification checklist

After re-enabling, verify the following before closing the incident:

1. Traffic resumes — check the audit log for requests successfully routed to the re-enabled provider within 1–2 minutes.
2. Health monitor state — confirm the health monitor has returned the (provider, model) pair to Active state. If the health monitor also disengaged the pair independently during the incident, the 300-second lockout must expire before the pair returns to normal routing.
3. Audit log completeness — verify the full incident is documented: activation entry, any requests blocked during the incident (look for outcome: BLOCK, block_reason: kill_switch), and the re-enable entry. Export this record if an incident report is required.
4. Fallback chain integrity — confirm that fallback chains are still correctly configured for the re-enabled provider; a kill switch activation may have revealed gaps.

Requests blocked by the kill switch appear in the audit log with outcome: BLOCK and block_reason: kill_switch. Group by api_key_id or user_id to identify the heaviest-affected callers.

---

When not to use the kill switch

The kill switch is intentional and manual. Do not use it as a substitute for proper configuration:

• Provider is unreliable or slow — configure fallback chains and let the health monitor handle transient failures.
• Cost optimization — use budget-based routing or Policy Engine ROUTE_TO rules to steer traffic away from expensive models.
• Testing routing — use ROUTE_TO rules in the Policy Engine. Do not activate and immediately deactivate the kill switch in production for testing.