Getting Started

Errors & missing data

Failures return { "error": { "code", "message", "details", "request_id" } }. Quote the request_id when contacting support.

Error codes

Code	HTTP	Meaning	Recommended action
`missing_api_key`	401	No API key was presented.	Send Authorization: Bearer <key>. The response carries WWW-Authenticate: Bearer.
`malformed_api_key`	401	The token is not a well-formed SimicX key, so it was rejected before any lookup.	Check for a truncated or re-wrapped paste: the shape is sxk_<env>_<16 chars>.<43 chars>.
`invalid_api_key`	401	The key is well-formed but not recognised.	Confirm the key in your platform profile; it may have been rotated.
`key_suspended / key_revoked`	401	The key exists but is no longer active.	Create a replacement key in your platform profile.
`key_expired`	401	The key's expires_at has passed.	Create a replacement in your platform profile; /v1/me/keys shows each key's expires_at.
`account_inactive`	403	The platform account behind the key is deactivated or deleted. Read live from the user record, so it takes effect immediately.	Contact your platform administrator — rotating the key will not help.
`ip_not_allowed`	403	The key carries an IP allow-list and this address is not on it.	Call from an allowed address, or ask an administrator to widen the list. error.details.ip is the address the service saw.
`endpoint_not_allowed`	403	The key's endpoint allow-list does not name this endpoint. It is the only gate on which routes answer. A key you create for yourself carries only the self-service endpoints (/v1/health, /v1/me, /v1/me/keys), so against a data route this means the endpoint has not been granted to your account or key yet.	error.details.endpoint is the registry id. /v1/me lists callable_endpoints — anything absent from that list will return this. Ask an administrator to grant the endpoint.
`alpha_not_allowed`	403	The key's alpha allow-list does not permit that alpha.	Call GET /v1/alphas for permitted alpha_id values.
`run_not_allowed`	403	The key's run allow-list does not permit that run. This is what a restricted key gets from /v1/alphas/{alpha}/… — the run list is checked first there.	Call GET /v1/alphas for permitted alpha_id values.
`bad_request`	400	One or more parameters are invalid — an out-of-range limit, an unknown sort or direction, a malformed date, or from after to.	error.details.parameters lists each offending parameter and the constraint it broke; other rejections name the parameter and the accepted values directly.
`unknown_book`	400	The run has no book by that name — or the key may not see it, which is deliberately indistinguishable.	error.details.available lists the books this key may read. Call …/books first.
`alpha_not_found / run_not_found / rebalance_not_found`	404	The address does not exist.	List GET /v1/alphas or …/rebalances. A missing rebalance date names the first, last, previous and next dates that do exist, so you never bisect the calendar.
`alpha_description_not_found`	404	The alpha exists but sealed no written description.	Only the incomplete seals are affected. Every other endpoint for the alpha still answers — treat the description as absent, not the alpha.
`source_not_ready`	404	No downloadable source ZIP is ready for this alpha yet — packaging may still be running, or it failed.	Retry later. error.details.status is present when the writer recorded a non-ready status. The alpha itself may still be listed as complete.
`source_object_missing`	404	The alpha's source ZIP is recorded as delivered, but the object is not in the store. The endpoint checks before it signs, so you get this instead of a signed URL that fails when you fetch it.	Not a transient failure — retrying will not help. Contact SimicX; an operator has to repackage the alpha.
`key_not_found`	404	No key with that key_id. Only reachable on the admin usage endpoint.	Platform operators only — check the key_id in the admin console.
`not_found / method_not_allowed`	404	No endpoint at that path, or a method other than GET. Raised by the router, before any key is read.	Every endpoint in this reference is a GET under /v1.
`rate_limit_second / rate_limit_minute / rate_limit_day`	429	The rate limit for that window was exceeded.	Honour Retry-After before retrying. The 429 also carries the live X-RateLimit-* headers.
`quota_exceeded`	429	The monthly request quota is exhausted.	Honour Retry-After — it points at the start of next month — and contact support for a higher limit.
`internal_error`	500	An unhandled failure. The body carries no detail by design.	Quote error.request_id to support. Retrying an identical request is unlikely to help.
`upstream_unavailable`	503	The results database is temporarily unreachable.	Retry with exponential backoff.
`benchmark_unavailable`	503	The market-data service backing /v1/benchmarks is temporarily unreachable.	Retry with exponential backoff. Only benchmark endpoints are affected; alpha data is served from a different store.
`benchmark_not_configured`	503	This deployment has no market-data service configured, so benchmark series cannot be served at all.	Not a transient failure — retrying will not help. Contact SimicX; on a self-hosted deployment it is a missing configuration value.
`source_download_unavailable`	503	The object store backing /v1/alphas/{alpha}/source/download failed while signing the URL.	Retry with exponential backoff. Only the source-download endpoint is affected.
`source_download_not_configured`	503	This deployment has no OSS credentials, so source ZIPs cannot be signed.	Not a transient failure — retrying will not help. Contact SimicX; on a self-hosted deployment set OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET.

Absence of data

A value the run measured but could not determine appears as an explicit null. A field the run never recorded is a different case: it is omitted rather than nulled, so read with .get() rather than indexing. raw_* mirrors (including raw_score) are stripped for keys without raw-book access. On /scores, forward_return is null when the run did not record it, and percentile_rank is not served. score is always the smoothed signal (direction × confidence), not raw_score. The catalogue list works the other way round: every row always carries alpha_id, name and tldr, with tldr null when the run recorded none.

When an alpha has no data at all for an endpoint, the response is 200 with an empty data array, pagination.total: 0, and a kind_missing warning in meta.warnings naming the kind. 404 is reserved for an address that does not exist. A metric that cannot be measured is returned as { "status": "not_measurable", "value": null, "withheld_reason": "…" }, never as zero.