Errors, request_id and troubleshooting

{
  "error": {
    "code": "permission_denied",
    "message": "Human readable message",
    "details": {}
  },
  "request_id": "req_123"
}

• 401 Unauthorized: invalid, expired or revoked credentials.
• 403 Forbidden: valid key, but scope or membership permission does not allow the action.
• 404 Not Found: the resource does not exist in the tenant scope of the key.
• 409 Conflict: idempotency-key reuse with a different payload or another write conflict.
• 429 Too Many Requests: per-key rolling rate limit exceeded.

• Persist request_id in logs, alerts and support tickets.
• Treat repeated 401 responses as credential lifecycle issues: revoke, rotate or re-issue.
• Treat 403 as a configuration or RBAC issue rather than a transient transport issue.
• Treat export download handling as a readiness poll instead of expecting a streamed file response.