# Errors Every error from the Contexory plugin API, the runtime API and trace ingest has the same shape. This page lists each code and what to do about it. Source: ## The error envelope An error response is JSON with one `error` object. `code` is stable and safe to branch on; `message` is for people and can change. ``` HTTP/1.1 401 Unauthorized Request-Id: req_3f9a1c0d5e7b4a2c8d6e1f0a9b8c7d6e { "error": { "code": "invalid_token", "message": "Missing or invalid runtime key", "request_id": "req_3f9a1c0d5e7b4a2c8d6e1f0a9b8c7d6e", "doc_url": "https://www.contexory.com/docs/reference/errors#invalid_token" } } ``` _A 401 response_ `request_id` is the same value as the `Request-Id` response header. Quote it when you contact support. `doc_url` links to the entry for the code on this page. `details` appears only when there is more to say, such as which fields failed validation. ## Headers on every response Every response from the API carries these, success or error: - **Request-Id**: an id for this request. Send your own `Request-Id` (8 to 64 letters, digits, dots, dashes or underscores) and it is echoed back; anything else is replaced. - **RateLimit-Limit**: the request budget per window for the bucket that applies. A limited response also has `RateLimit-Remaining` and `RateLimit-Reset`. - **Retry-After**: seconds to wait, on every `429` and `503` that Contexory's own code sends. A request stopped by the edge firewall before it reaches Contexory has no body in this format. ## invalid_token Status 401. The token is missing, malformed, revoked or expired, or it is the wrong kind for this route (a runtime key where an ingest key is needed). The response carries a `WWW-Authenticate` header. Check the `Authorization: Bearer` header and create a new key if needed. Retrying the same request will not help. ## insufficient_scope Status 403. The token is valid but only allows reading, and this route writes. Use a token with write access. ## delivery_key_required Status 403. Only a delivery key can record a delivery receipt, and a runtime key was used. Use the delivery key from your CI secrets. ## forbidden Status 403. The token is valid but is not allowed to reach this target, for example an agent outside the runtime key's scope. Use a key scoped to that agent, or pick another target. ## feature_disabled Status 403. The feature is not turned on for this workspace. Unlike `not_found`, the route exists: retrying will not help until the feature is enabled for the workspace. ## subscription_inactive Status 402. The workspace's billing is inactive, so sync and writes are paused. Reactivate a plan in the workspace's billing settings. ## not_found Status 404. No route, or no row in the token's workspace, matches the request. A row in another workspace looks the same on purpose. Check the path, the slug or the id. ## validation_error Status 400. The request is malformed, for example a body that fails validation, a bad path or an invalid label. The `details` field says what. Fix the request; do not retry it unchanged. ## payload_too_large Status 413. The request body is over the size limit. Send fewer spans per request or compress the body with gzip. ## unsupported_media_type Status 415. The content type or encoding is not accepted. Send `application/json` or `application/x-protobuf`, with `gzip` or no encoding. ## conflict Status 409. The request conflicts with the current state, for example an active review is already open or there is nothing to publish. Read the message, fix the state, then retry. ## rate_limited Status 429. Too many requests for this key or IP address. The response carries `Retry-After` and the `RateLimit-*` headers. Wait for `Retry-After` seconds, then retry with backoff. ## internal Status 500. Something failed on Contexory's side. Retry with backoff. If it persists, send support the `request_id`. ## bad_gateway Status 502. A file stored for the skill could not be fetched from storage. Retry with backoff. ## unavailable Status 503. Contexory is missing something it needs to answer, or a dependency is down. The response carries `Retry-After`. Retry after that many seconds.