Error catalog

Every error code, what triggers it, and how to fix it.

Uniform K8 v2 envelope:

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "modification_extent must be between 0.0 and 1.0",
    "request_id": "req_01H...",
    "timestamp": "2026-04-22T18:22:10.432Z"
  }
}

Catalog

Status	Code	Meaning	Fix
400	`INVALID_JSON`	Body was not valid JSON	Check `Content-Type`, validate JSON client-side
401	`UNAUTHORIZED`	Missing, unknown, inactive, expired, rate-limited, or bad-hash key	See authentication
404	`NOT_FOUND`	Resource does not exist	Check operator_id, path spelling
413	`PAYLOAD_TOO_LARGE`	Body exceeds 1 MB (single) or 5 MB (batch)	Split into smaller batches
422	`VALIDATION_FAILED`	Enum, range, or schema violation	Read `message`; check schema
422	`OPERATOR_ID_INVALID`	operator_id failed regex	Alphanumeric + `-_`, 1-256 chars
422	`INSUFFICIENT_DATA`	Not enough interactions yet	Need 50 interactions or 10 days
429	`RATE_LIMITED_IP`	Per-IP throttle (pre-auth)	Back off per `Retry-After`
429	`RATE_LIMITED_KEY`	Per-key throttle (post-auth)	Back off per `Retry-After`
500	`INTERNAL_ERROR`	Unexpected server error	Include `request_id` when you report

Uniform auth envelope

All auth failures return the same shape with an 80 ms floor. The real reason is written to audit_log, never to the client. This is intentional, see security.

Request IDs

Every response, success or failure, carries request_id. Quote it when filing a support ticket.

Next step

Rate limits for 429 handling.
Support for response SLAs.