Errors

JSON error shape (HTTP API)

Non-2xx responses use a nested error object:

JSON

{
  "error": {
    "type": "api_error",
    "code": "authentication_error",
    "message": "Invalid API key",
    "param": null,
    "request_id": ""
  }
}

type is invalid_request for HTTP 422 validation failures, otherwise usually api_error.

Responses include x-request-id (and x-strike-api-version) headers.

HTTP status codes

Status	`code` (typical)	Meaning
400	`danger_zone_required`, `max_tokens_exceeded`, `invalid_image`	Danger Zone header missing, window over the cap, or an image the API rejects
401	`authentication_error`	Missing or invalid Bearer token
402	`payment_required`	No credits left and pay as you go is not active
403	`forbidden`	Authenticated, but not allowed (admin routes)
404	(varies)	Resource not found
409	`key_limit`	The account already has the maximum number of active API keys
413	`payload_too_large`	Body over the proxy limit, or a trace batch over 1 MB
422	`validation_error`	Request failed schema or engine validation
429	`rate_limited`	Plan requests-per-second limit. `Retry-After` is set (seconds)
429	`quota_exceeded`	Free allowance of 10 decisions per day is used up, or the legacy daily quota
500	`internal_error`	Unexpected failure while saving a signup or similar
503	`model_warming`	strike-1 is starting up. Retry after `Retry-After` when present
503	`storage_error`	A trace batch could not be stored
529	`engine_unavailable`, `inference_overloaded`	Engine not ready, or the process in-flight cap is hit

HTTP 530 is not an API status. Some edges and older SDK notes used it for a tunnel that was down. strikeflow still retries 530 if a proxy emits it. Treat it as an edge or SDK retry, not a Strike error code.

Proxy-only 429 body example:

JSON

{
  "error": {
    "type": "rate_limit",
    "code": "too_many_requests",
    "message": "Too many requests. Try again shortly."
  }
}

Free allowance (platform keys, before the account has paid): HTTP 429 with code quota_exceeded.

Python exceptions (strike-ai)

strike_ai.Client.decide calls httpx and raises httpx.HTTPStatusError on any 4xx or 5xx. The JSON error body above is available on exc.response.json(); check exc.response.status_code for 402 and 429 and read Retry-After from exc.response.headers before retrying. Connection failures raise httpx.TransportError.

Python exceptions (strikeflow)

Catch strike.StrikeError for all SDK failures. NotFoundError and InternalServerError are exported from strikeflow.

Exception	When
`APIConnectionError`	DNS, TLS, connection reset
`APITimeoutError`	Request timed out
`AuthenticationError`	HTTP 401 or 403
`RateLimitError`	HTTP 429
`NotFoundError`	HTTP 404
`InternalServerError`	HTTP 5xx, including a proxy 530
`APIStatusError`	Other non-2xx

APIStatusError exposes status_code, body, and request_id.

Retries

StrikeModel retries 408, 409, 429, 5xx, 530 and connection/timeouts up to max_retries (default 2) with jittered backoff, honouring Retry-After when present. It does not retry 402.

Python

import strikeflow as strike

strike.configure(max_retries=3, timeout=45.0)

Decision tool errors

strike_decision_tool().handle(...) does not raise for decision failures. It returns {"error": "..."} so the host LLM loop can continue.

User-facing copy

The console maps common statuses to short titles in its error catalogue (401, 402, 404, 413, 422, 429, 529, 503 model warming, network). Use those messages in UI. In backend code, check status_code and error.code.