Errors, pagination, and idempotency

Envelope

Success responses include data and meta.requestId. Errors include error.code, error.message, and the same request id. Echo X-Request-Id if you send one.

Status codes

• 400 validation or missing tenant/user headers
• 401 missing or invalid key
• 403 permission, entitlement, expired key, or sandbox mismatch
• 404 unknown resource or disabled module
• 409 idempotency key reused with a different body
• 429 rate limit — honor Retry-After and RateLimit-*

Pagination

List endpoints accept limit and offset. Prefer cursor when present for stable pages.

Idempotency

Mutations accept Idempotency-Key. The same key and body replay the stored result for 24 hours. A different body with the same key returns 409.