Errors, retries and pagination
Handle uncertainty without duplicating work.
{"error":{"code":"insufficient_scope","requestId":"…","details":{"requiredScope":"posts:write"}}}Every response has X-Request-ID. Errors use stable codes: 400 invalid input/rejected review, 401 invalid key, 402 plan/credits/quota, 403 missing scope, 404 missing or foreign resource, 409 version/voice/idempotency conflict, 413 oversized payload, 429 limits, 502/503 provider or service unavailable. Store the request ID for support, never your API key.
Idempotency-Key (8–128 letters/digits/underscore/hyphen) is required for post creation, AI/Jev calls, voice refresh and preferences. Keys are scoped to the user and operation family, not the API credential: use unique values across integrations. Post creation and voice refresh replay the original operation. AI/Jev/customization duplicate submissions return 409 and do not repeat the provider call; responses are not cached for replay. On timeout, inspect the resource/request history before starting a new operation. Preferences can have saved successfully even if the response was lost: read back their revision. Do not blindly retry writes with a new key.
List endpoints return nextCursor (opaque) or voice nextBefore. Follow until null; default page size 20, maximum 50 (voice versions: 20). Calendar queries require from/to milliseconds with a maximum range of 93 days. Bodies are JSON, maximum 128 KB overall; voice has a 32 KB cap and individual endpoints impose stricter field/context limits.