Error Codes

This page documents every error code returned by the three Arbitex services — Platform (gateway + admin API), Cloud (portal API), and Outpost (proxy + admin API). Each entry includes the error code, HTTP status, which service produces it, what triggers it, and how to resolve it.

---

Error Response Formats

Each service uses a slightly different error envelope. Your client code should handle all three formats.

Gateway / Outpost Proxy

The gateway and outpost proxy use a nested error object matching the OpenAI error format:

{
  "error": {
    "message": "Rate limit exceeded. Retry after 2026-03-08T14:33:00Z.",
    "type": "rate_limit_error",
    "code": "quota_exceeded"
  }
}

The type field classifies the error category. The code field (when present) provides a machine-readable identifier. Some errors include additional fields like rule_id.

Cloud Portal API

The Cloud service uses a flat envelope with a status-derived error code:

{
  "error": "forbidden",
  "detail": "API key has been revoked"
}

The error field maps directly from the HTTP status code. The detail field provides a human-readable description.

Platform Admin / Outpost Admin

The Platform and Outpost admin APIs use the standard FastAPI format:

{
  "detail": "Invalid credentials"
}

Some Platform middleware endpoints add extra fields:

{
  "detail": "MFA verification required to access this resource",
  "mfa_required": true
}

---

Gateway & Outpost Proxy Errors

These errors are returned by the primary AI completions endpoint (POST /v1/chat/completions) on both the hosted gateway and on-premises outpost proxy.

Authentication Errors

Code / Type	HTTP	Description	Resolution
invalid_api_key	401	API key not found, revoked, or malformed.	Verify the key exists in Settings > API Keys. Check for leading/trailing whitespace. Ensure the arb_live_ or arb_test_ prefix is present.
authentication_error	401	Authorization header missing or invalid. JWT validation failed (expired, bad signature, unknown kid).	For API key auth: include Authorization: Bearer <key> or X-API-Key: <key>. For JWT auth: ensure the token is not expired and the JWKS endpoint is reachable.
authentication_error	403	JWT missing required scope for the requested resource.	Check that the JWT contains the required scopes. Review the OAuth client’s configured scopes in Settings > OAuth Clients.

Policy Errors

Code / Type	HTTP	Description	Resolution
policy_block	403	Policy Engine terminal action is BLOCK. The rule_id field identifies which rule matched.	This is not retriable — the same request will be blocked until the policy changes. Review the matched rule in Admin > Policy Engine. Check user group membership and model access rules.
dlp_violation	403	DLP pipeline detected sensitive content and the action is BLOCK or CANCEL. Applies to both input and output scanning.	Review the DLP rules that triggered the block. If the content was a false positive, adjust the DLP rule’s sensitivity or add an exception. Check X-DLP-Action header for the specific action taken.

Rate Limit & Budget Errors

Code / Type	HTTP	Description	Resolution
quota_exceeded	429	Organization or user rate limit exceeded.	Inspect X-RateLimit-Reset header for window reset time. Implement exponential backoff. Contact your admin to adjust rate limits if consistently hitting caps.
rate_limit_error	429	Outpost-local rate limit exceeded.	Check Retry-After header. The outpost enforces its own rate limits independently of the platform. Adjust outpost rate limit configuration in RATE_LIMIT_* environment variables.
budget_exceeded	429	Monthly dollar cap or request cap exceeded on the outpost. X-Budget-Status: exceeded header is set.	Budget limits are configured per-outpost. Review budget settings in the outpost admin panel or adjust BUDGET_* environment variables. Limits reset at the configured period boundary.

Provider Errors

Code / Type	HTTP	Description	Resolution
provider_unavailable / provider_error	502	All providers in the routing/fallback chain failed (5xx, connection error, or timeout from upstream).	Retry with exponential backoff. Check provider health at GET /api/providers/health. Review your fallback chain configuration. If persistent, the upstream provider may be experiencing an outage.
providers_disabled	503	Every provider for the requested model is disabled by local admin override on the outpost.	Check outpost overrides in the admin panel. Re-enable at least one provider for the model.
override_error	503	A routing override references a provider name not present in the policy bundle.	Remove or correct the override in the outpost admin panel. Ensure the provider name matches exactly (case-sensitive).
model_not_found / invalid_request_error	400/404	The requested provider/model-id is not recognized, not available for your organization, or not in the policy bundle.	Verify the model ID format (provider/model-id). Check available models at GET /v1/models or in the model catalog.

Request Validation Errors

Code / Type	HTTP	Description	Resolution
invalid_request	400	Malformed request body — missing required fields or invalid types.	Validate your request body against the Chat Completions schema. Ensure Content-Type: application/json is set.
context_length_exceeded	400	The request (system prompt + messages + max_tokens) exceeds the model’s context window.	Reduce message history, shorten the system prompt, or lower max_tokens. Check the model’s context limit in the Model Catalog.
request_too_large	413	Request body exceeds the outpost’s MAX_REQUEST_BODY_MB limit.	Reduce the request payload size. The default limit is configured per-outpost.
invalid_request	415	Content-Type header is not application/json.	Set Content-Type: application/json on all POST requests.

Service Errors

Code / Type	HTTP	Description	Resolution
emergency_kill	503	The outpost emergency kill switch is active. All requests are rejected.	The local admin has activated the kill switch. Contact your outpost administrator to restore service via POST /admin/api/override/kill-switch with active: false.
service_unavailable	503	The outpost has not yet loaded a policy bundle from the platform.	Wait for the outpost to complete its initial sync. Check outpost logs for policy bundle sync errors. Verify the PLATFORM_MANAGEMENT_URL is correct and reachable.
internal_error	500	Proxy router not initialized or unexpected internal error.	This indicates an outpost startup issue. Check outpost logs. Restart the outpost if the error persists.

---

Cloud Portal API Errors

The Cloud service normalizes all HTTP errors to a consistent envelope: {"error": "<code>", "detail": "<message>"}.

Standard Error Codes

error Code	HTTP	Description	Resolution
bad_request	400	Malformed request — invalid JSON, missing required fields, or invalid parameter values.	Check the request body against the API specification. Ensure all required fields are present and correctly typed.
unauthorized	401	Missing or invalid authentication. No Bearer JWT or X-API-Key header provided, or the token is expired/invalid.	Include a valid Portal JWT (Authorization: Bearer <token>) or API key (X-API-Key: <key>). If the JWT expired, re-authenticate through the portal login flow.
forbidden	403	Access denied. Common causes: API key revoked, API key expired, JWT org_id mismatch (IDOR prevention), insufficient role, missing scopes.	Check that the API key is active and not expired. Verify the JWT’s org_id matches the URL’s {org_id} parameter. Ensure the authenticated user has the required role (e.g., org_admin for write operations).
not_found	404	Resource not found. The org, outpost, notification, job, or other referenced resource does not exist or belongs to a different org.	Verify the resource ID. Check that the org is active (not cancelled). Ensure the org_id in the URL matches the authenticated context.
conflict	409	Conflict — typically a duplicate resource creation (e.g., registering an outpost with a name that already exists).	Use a different identifier or check if the resource already exists before creating.
validation_error	422	Request body failed schema validation (Pydantic). The detail field contains specific field-level error messages.	Review the validation errors in detail. Fix the request body to match the expected schema.
rate_limit_exceeded	429	Org-level rate limit exceeded (per-plan). Response includes limit, reset_at, and message fields.	Implement exponential backoff. Check the reset_at timestamp in the response. Rate limits are per-plan — contact sales to increase limits.
internal_error	500	Unhandled server error.	Retry once. If persistent, this is a server-side bug — contact support with the request ID.

Authentication-Specific Errors

Trigger	HTTP	detail Message	Resolution
JWT expired or invalid signature	401	Invalid or expired JWT: <reason>	Re-authenticate to obtain a fresh JWT. If using service-to-service auth, verify the JWT signing key configuration.
JWT missing sub claim	401	JWT missing sub claim	The JWT was issued without a subject claim. This indicates a misconfigured token issuer.
Bulk token revocation	401	Token predates a bulk revocation event — please re-authenticate	An admin performed a bulk token revocation. All sessions before the revocation timestamp are invalidated. Re-authenticate.
Individual token revoked	401	Token has been revoked	This specific token was revoked (e.g., by admin session management). Re-authenticate.
API key invalid	401	Invalid API key	The API key hash does not match any key in the database. Verify the key was copied correctly.
API key revoked	403	API key has been revoked	The key was explicitly revoked. Issue a new key from Settings > API Keys.
API key expired	403	API key has expired	The key’s expires_at date has passed. Issue a new key or update the expiry on the existing key.
Role insufficient	403	Role '<role>' does not have permission for this resource	The operation requires a higher role (e.g., org_admin). Contact your org admin.
Missing scopes	403	Missing required scopes: <scopes>	The API key does not have the required scopes. Update the key’s scope configuration.
No credentials	401	Missing authentication: provide Bearer JWT or X-API-Key header	Include an authentication header. Both Authorization: Bearer <jwt> and X-API-Key: <key> are accepted.

---

Platform Admin API Errors

The Platform admin API uses FastAPI’s default error format ({"detail": "..."}) with middleware-specific extensions.

Authentication & Authorization

Trigger	HTTP	Response	Resolution
Email already registered	409	{"detail": "Email already registered"}	Use a different email or reset the password on the existing account.
Username taken	409	{"detail": "Username already taken"}	Choose a different username.
Weak password	422	{"detail": "Password must be at least 8 characters and contain at least one uppercase letter and one number"}	Use a stronger password meeting the stated requirements.
Bad credentials	401	{"detail": "Invalid credentials"}	Verify email and password. Check that the account is active.
MFA required	403	{"detail": "MFA verification required to access this resource", "mfa_required": true}	Complete the MFA challenge. The X-MFA-Required: true response header is also set. Submit a TOTP code to POST /api/auth/mfa/verify.

mTLS Errors (Internal Endpoints)

Code	HTTP	detail Message	Resolution
mtls_not_configured	503	Internal endpoints require mTLS configuration.	The Platform’s mTLS is not configured. Set MTLS_CA_CERT_PATH and related environment variables.
cert_required	401	Client certificate required for internal API access.	Include a valid client certificate in the TLS handshake. Cloud-to-Platform calls require the Step CA-issued mTLS cert.
cert_expired	403	Client certificate is expired or not yet valid.	Renew the client certificate. For outposts, use POST /v1/orgs/{org_id}/outposts/{outpost_id}/renew. For Cloud, check the Step CA certificate rotation.
cert_untrusted	403	Client certificate is not issued by the trusted Cloud CA.	The certificate was not signed by the configured CA. Ensure the certificate chain is correct and the CA bundle is up to date.

IP Allowlist

Code	HTTP	Response	Resolution
ip_not_allowed	403	{"error": "ip_not_allowed", "detail": "Client IP not in organization allowlist"}	Add the client IP to the organization’s allowlist in Admin > Security > IP Allowlist.

Rate Limiting & Throttling

Trigger	HTTP	Response	Headers	Resolution
Rate limit	429	{"detail": "Rate limit exceeded"}	Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset	Wait until Retry-After or X-RateLimit-Reset. Implement exponential backoff.
Usage throttle	429	{"detail": "Monthly usage limit reached", "upgrade_url": "/billing/upgrade", "retry_after_seconds": N}	—	Upgrade your plan or wait for the monthly reset.

Request Validation

Trigger	HTTP	Response	Resolution
Body too large	413	{"detail": "Request body exceeds maximum size of N bytes"}	Reduce the request payload. Check MAX_REQUEST_BODY_BYTES configuration.
Wrong content type	415	{"detail": "Content-Type must be application/json for API requests"}	Set Content-Type: application/json.

---

Outpost Admin API Errors

The Outpost admin API (port 8301) uses FastAPI’s {"detail": "..."} format. All endpoints require admin API key authentication.

Authentication

Trigger	HTTP	detail	Resolution
No auth header	401	Authorization header required	Include Authorization: Bearer <admin-api-key> or X-Admin-Key: <key>.
Not Bearer format	401	Bearer token required	Use Bearer scheme in the Authorization header.
Empty key	401	Empty API key	Provide a non-empty API key.
JWT revoked	401	Token has been revoked	The JWT’s jti is in the revocation list. Obtain a new token.
JWT expired	401	JWT has expired	The token’s exp claim is in the past. Authenticate again via POST /admin/api/auth.
Bad API key	403	Invalid admin API key	The key doesn’t match the configured ADMIN_API_KEY hash. Verify the key.
JWT not configured	501	Admin JWT not configured	JWT-based admin auth is not enabled. Either configure ADMIN_JWT_SECRET or use API key auth.

Resource Errors

Trigger	HTTP	detail	Resolution
Session not found	404	Session not found	The session ID does not exist or has already expired.
Hold not found	404	Hold not found or already resolved	The prompt hold was already approved/rejected, or the ID is invalid.
Plugin not found	404	Plugin '<name>' not found	The plugin name is not in the registry. Check available plugins via GET /admin/api/plugins.
Pattern not found	404	Pattern '<name>' not found	The custom redaction pattern doesn’t exist. List patterns via GET /admin/api/custom-patterns.

Feature Gates

Trigger	HTTP	detail	Resolution
Plugin system disabled	503	Plugin system not enabled	Set PLUGIN_SYSTEM_ENABLED=true in the outpost configuration.
Custom patterns disabled	503	Custom patterns not enabled	Set CUSTOM_PATTERNS_ENABLED=true in the outpost configuration.
Not in multi-org mode	400	Not in multi-org mode	The endpoint requires multi-org mode. Configure MULTI_ORG_ENABLED=true.

Initialization Errors

Trigger	HTTP	detail	Resolution
Settings not loaded	500/503	Settings not initialised	The outpost is still starting up. Wait for initialization to complete, then retry.
Override store not ready	500	Override store not initialised	The override store hasn’t loaded yet. This resolves after the first policy bundle sync.
Prompt hold store not ready	500	Prompt hold store not initialised	The prompt hold subsystem hasn’t initialized. Check outpost logs for startup errors.

Validation Errors

Trigger	HTTP	detail	Resolution
Invalid JSON body	400	Invalid JSON body	Ensure the request body is valid JSON.
Missing fields (custom pattern)	400	'name' and 'pattern' are required	Include both name and pattern fields when creating a custom redaction pattern.
Bad regex	400	<regex error>	The regex pattern failed to compile. Fix the regex syntax.
Missing API key	400	api_key is required	Include the api_key field in the authentication request body.

---

Outpost Middleware Errors

These errors are returned by outpost middleware layers before the request reaches the proxy handler.

Source	HTTP	Response Format	Resolution
Rate limiter	429	{"error": "rate_limit_exceeded", "retry_after": <seconds>}	Wait for retry_after seconds. Adjust RATE_LIMIT_* settings for higher throughput.
IP allowlist	403	{"detail": "IP address not in allowlist", "client_ip": "<masked>"}	Add the client IP to the outpost’s allowlist via PUT /admin/api/ip-allowlist.

---

HTTP Status Code Quick Reference

Status	Meaning	Retriable?
400	Bad request — fix the request and resend	No
401	Authentication failed — provide valid credentials	No (re-authenticate first)
403	Forbidden — insufficient permissions, policy block, or IP not allowed	No (change config/permissions)
404	Resource not found	No
409	Conflict — duplicate resource	No
413	Payload too large	No (reduce payload)
415	Unsupported media type	No (fix Content-Type)
422	Validation error — fix request body	No
429	Rate limited or budget exceeded	Yes (after backoff)
500	Internal server error	Yes (once)
501	Feature not configured	No (enable feature)
502	Upstream provider failure	Yes (with backoff)
503	Service unavailable (kill switch, startup, mTLS)	Depends on cause

Tip

For 429 errors, always check Retry-After or X-RateLimit-Reset headers before retrying. For 502/503 provider errors, implement exponential backoff with jitter starting at 1 second.