Errors, command retries and pagination
The API returns HTTP status and application/problem+json. Each operation lists its error schema. 401 means credential or scope; 403 creator access; 404 unavailable resource; 409 a version, idempotency or state conflict; 429 throttling; 503 temporary unavailability.
Idempotency-Key
Choose a unique 8–160 character key: start with a letter or digit; continue with letters, digits, dot, underscore, colon or hyphen. After timeout, retry the same method, URL, body and key. A different body with the same key returns 409; a new key may create a second effect. Check each read-only POST parameter list.
expectedVersion protects against lost updates. After 409, read current state and deliberately rebuild the command. A receipt confirms an accepted command, not asynchronous delivery completion. Never retry money or sending blindly with a new key.
Rate limits
Developer API has a separate budget from browser sessions. Follow Retry-After on 429 and use backoff for transient failures, retaining the same write key. Rate-store failure closes ingress with 503. Plan capabilities and enabled modules are checked separately.
Data pages
Cursor catalogs use limit (usually 50, maximum 100) and nextCursor. Cursors are opaque and bound to original filters: keep them unchanged across pages. Continue after an empty page with nextCursor. Lists are not full database snapshots. See each method schema for exact limits.