Error codes

Every error response uses the same envelope: { "code": …, "message": …, "correlationId": … }. 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_<prefix>.<secret>; 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.