Errors

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"
  }
}

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.