API reference

Errors

Every error response is JSON with a consistent envelope. Status codes follow REST conventions and the body always carries a stable, machine-readable shape.

Envelope

Typical 4xx body
{
  "statusCode": 401,
  "message": "Missing scope: validate",
  "error": "Unauthorized"
}
  • statusCode mirrors the HTTP status, included so SDKs can centralize handling without parsing the status line.
  • message is human-readable. Safe to surface back to the model — they’re short and don’t leak internals.
  • error is the high-level category, e.g. Unauthorized, BadRequest,NotFound.

Status codes you might see

FieldTypeDescription
200
OK
Successful response. On validate and propose a 200 with allowed: false is still a 200 — the policy did its job.
400
Bad Request
Malformed JSON, missing required fields, unknown enum values. Inspect message — these are not retry-safe.
401
Unauthorized
Bad bearer, expired key, revoked key, or missing scope for this route. Not retry-safe; rotate the key.
403
Forbidden
RBAC permission denial — for org members whose role lacks the permission. Not retry-safe.
404
Not Found
Unknown route or resource id. Often a typo in the path.
409
Conflict
Idempotency-Key collision on propose with a different payload for the same key. Use a fresh key or wait 24 hours.
429
Too Many Requests
You hit the throttle (100/min/user). Back off with exponential delay. See Rate limits.
500
Internal Server Error
Bug or transient failure on our side. Retry-safe — exponential backoff with jitter.
502 / 503 / 504
Edge / upstream
Gateway, capacity, or timeout at the edge. Retry-safe.

Retry policy

  • Retry on 5xx and 429. Exponential backoff starting at 250ms with jitter, capped at ~10s. Give up after 5 attempts.
  • Don’t retry 4xx. Fix the request instead.
  • Use Idempotency-Key on propose so retries don’t create duplicate attestation requests.

Violation rules

The violations array inside a validate_trade response uses a small fixed vocabulary documented on the Validate trade page. Per-key policy violations carry a key_policy_* prefix and are documented on the Per-key policy constraints page.

Last updated 2026-06-15
Suggest an edit·Changelog