Reference

Craton error reference

Every refusal the API makes has one shape, whatever route made it and whatever went wrong. This page is the specification of that shape: the envelope, every field in it, every code Craton reports, and the rules that say what can change under you and what cannot.

Write the failure path once. It is the same path for all of them.

The envelope

A response with an HTTP status of 400 or above always carries this body, including the ones raised before any handler runs (an unknown path, a method a route does not serve, a body that would not parse) and including a 500.

{
  "schema_version": "0.1.0",
  "error": {
    "status": 401,
    "code": "unauthenticated",
    "message": "this endpoint requires an API key: send 'Authorization: Bearer <your key>'"
  }
}

The formal specification is error.v0.schema.json, published open source alongside the risk object schema and consumable without a Craton account. The API contract document api-contract.v0.json states, in machine-readable form, that this schema governs every status of 400 or above from every route, and lists the codes below under errors.named_codes. Both files are generated from the running server, not maintained by hand.

Both are served by this documentation site, with no account and no key: /schema lists everything published, /schema/error.v0.schema.json is the envelope above, and /schema.json is the canonical risk object. They are the same files Craton validates its own responses against, so when a refusal below names a schema, that is a document you can fetch and read, not a path inside a repository you do not have.

Fields

No other member appears at either level: the schema sets additionalProperties: false on both objects, so a body carrying anything else is a product bug and the contract oracle fails on it.

details in use. It is the same envelope, one member richer:

{
  "schema_version": "0.1.0",
  "error": {
    "status": 422,
    "code": "invalid_request",
    "message": "a signup request reads two optional members, 'email' and 'label'",
    "details": ["unknown member: nope"]
  }
}

Two headers carry information the body does not: WWW-Authenticate: Bearer on a 401, and Retry-After (seconds) on a 429.

A refusal is a fact about a request: malformed, unauthenticated, outside a verb's scope. It is never a statement about risk appetite and never a commercial position of any kind.

The codes

Every code Craton reports. status is the HTTP status (and error.status) the code arrives with.

One ordering fact worth knowing before you debug a 404: the key is checked before the path is. An unknown path presented without a credential answers 401 unauthenticated, not 404 not_found: the API does not disclose which of its paths exist to a caller it cannot identify. Send the key and the same request answers 404.

What may change, and what may not

error.code is specified as a pattern, not a closed enum, and that is deliberate. A failure mode nobody predicted must be reportable honestly the moment it exists, without waiting for a schema version bump. The alternative is a platform that reports new failures as something they are not.

So write your client this way:

• Switch on error.code for the codes above that you handle specifically.
• Fall back to error.status for anything else. A code you have never seen still arrives inside the envelope above, at a status whose meaning is ordinary HTTP.
• Never match on error.message. Messages are written for humans and are revised whenever a clearer sentence exists.

What will not change without a major version of the error schema: the envelope, the three mandatory fields, additionalProperties: false, and the rule that every status of 400 or above uses this shape. The table above may grow.

Failures on jobs

Every Craton verb answers with a job. A job that fails carries the same refusal, minus the envelope, as the error member of the job resource:

{
  "schema_version": "0.1.0",
  "id": "0f6b6f4e-8a5b-4c1d-9d2a-3c7e5b1f0a44",
  "verb": "price",
  "status": "failed",
  "created_at": "2026-08-11T04:11:00.000000Z",
  "updated_at": "2026-08-11T04:11:00.412000Z",
  "links": { "self": "/jobs/0f6b6f4e-8a5b-4c1d-9d2a-3c7e5b1f0a44" },
  "error": {
    "status": 422,
    "code": "unpriceable_object",
    "message": "Price v0 cannot price this object: no trigger"
  }
}

The three fields mean exactly what they mean in a synchronous refusal, and the codes are the same codes: a failure is a job state, not a dropped connection, and GET /jobs/{id} answering 200 with a failed job is the correct outcome: the job resource was served, and it says the work did not succeed. Check status == "failed", then read error.

Which faults answer on the request, and which on the job

One rule, and it holds for every verb: a fault the platform can know without doing the work is answered on the request; a fault it can only discover by doing the work is answered on the job. A POST that starts a job does not do the work (that is what the job is), so it can only refuse what is already knowable when it is called.

Knowable at the door, and therefore a 4xx from the POST itself: the credential (unauthenticated, rate_limited), the account's standing (account_cancelled), the shape of the request (unsupported_media_type, invalid_request, payload_too_large), the existence of what it names (not_found), and the few refusals that read a document already in the store (unknown_analysis, unpackageable_object, invalid_structure).

Discovered by doing the work, and therefore on the job: unsupported_source, currency_conflict, unpriceable_object, unbacktestable_structure, unanalysable_object, unrunnable_object. (The split is about where a fault is discovered, not about which codes exist: a subject that goes away between the POST and the work fails the job with the same not_found the request would have answered.)

unsupported_source is the one that catches people out, so it is worth being explicit. POST /ingest answers 202 even for a file that is obviously not a schedule: a text file with no delimiter anywhere in it, say, declared as text/csv. The declared type is checked at the door, because a declaration can be read without opening the file; whether the bytes are delimited text cannot be, and finding out is the first thing the ingest job does. So the job is created, runs, and finishes failed with 415 unsupported_source in error. There is no synchronous form of that refusal, and no request flag that asks for one: poll the job.

currency_conflict splits the same way, and shows the rule twice on one field. POST /ingest takes an optional currency part: the ISO 4217 code you state for a schedule that names no currency of its own. Whether that code is three letters is a fact about the request, so a malformed one answers 422 invalid_request from the POST. Whether the file agrees with it is a fact about the file's cells and headers, so a code the file contradicts answers 422 currency_conflict on the job.

The status codes are the same either way. A client that switches on error.code and error.status handles both paths with one branch. The only difference is whether it read them off the POST response or off the job it polled.

Validating against the published schema

The schema is a file, not an API call. Fetch error.v0.schema.json from the public schema repository and validate refusals against it in your own tests. It is JSON Schema draft 2020-12, so any standard validator reads it. If a Craton response ever fails that validation, that is a Craton bug: report it rather than loosening your validator.

The same holds in the other direction. Craton's own gate validates every response the API produces against these published files on every change, so this page and the product cannot quietly drift apart.

A worked example

curl -sS -i "$CEDE_BASE_URL/ingest" -X POST

HTTP/1.1 401 Unauthorized
www-authenticate: Bearer
content-type: application/json

{"error":{"code":"unauthenticated","message":"this endpoint requires an API key: send 'Authorization: Bearer <your key>'","status":401},"schema_version":"0.1.0"}

(Craton serves canonically-ordered JSON, so members arrive sorted by name. Member order is not meaning: read the body with a JSON parser, never by position.)

Handling it, with nothing installed:

response=$(curl -sS -w '\n%{http_code}' "$CEDE_BASE_URL/ingest" -X POST)
body=${response%$'\n'*}
code=$(printf '%s' "$body" | python3 -c 'import json,sys; print(json.load(sys.stdin)["error"]["code"])')

case "$code" in
  unauthenticated)  echo "check CEDE_API_KEY" ;;
  rate_limited)     echo "wait and retry" ;;
  *)                echo "unhandled: $body" ;;
esac

See also: the quickstart, whose When it does not work section lists the refusals you are most likely to meet on your first run.