Error codes

Every error response uses the same envelope. Branch on the stable code, never on message. This table is generated from the OpenAPI contract’s error-code enum, so it can never omit or invent a code.

Code	HTTP status	What to do
UNAUTHENTICATED	401	Send Authorization: Bearer gck_live_.; check the key isn’t revoked or expired (rotate it on the API Keys page).
FORBIDDEN	403	The key is read-only; mint or rotate a read-write key for writes.
RESOURCE_NOT_FOUND	404	The id is outside your key’s scope or doesn’t exist; confirm you own or manage the listing with writer access.
INVALID_CURSOR	400	Pass the nextCursor value verbatim; don’t construct or mutate cursors.
VALIDATION_ERROR	400	Fix the fields listed in errors[]; check types and required fields against the reference.
PAYLOAD_TOO_LARGE	413	Reduce the request body size or field count below the documented caps.
RATE_LIMITED	429	Back off and retry after the Retry-After header’s seconds; reduce request rate per key.
IDEMPOTENCY_KEY_REUSED	422	The Idempotency-Key you sent was already used for a request with a different body. Use a fresh key for a new request, or resend the byte-identical body to replay the original result.