Skip to main content

Troubleshooting

Collect these fields first​

  • realm_id
  • principal_id
  • billing_account_id (if known)
  • endpoint and method
  • Idempotency-Key (for writes)
  • X-Request-Id (if set)
  • full response envelope (redacted as needed)

Common issues​

401 or 403​

Likely causes:

  • wrong realm id
  • invalid service key
  • bearer token expired

Actions:

409 conflict​

Likely cause:

  • same Idempotency-Key reused with a different request body

Actions:

  • ensure retries reuse the same key and same body

422 validation failed​

Likely causes:

  • invalid identifiers
  • invalid feature or meter codes
  • policy window not found

Actions:

  • confirm inputs and compare with OpenAPI schemas

429 rate limited​

Actions:

  • implement backoff
  • confirm you are not retrying with new idempotency keys
  • treat sustained 429 as a capacity or policy signal

402 payment required​

Likely causes:

  • insufficient balance
  • quota or budget enforcement

Actions:

  • inspect hints and apply your product policy (top-up, degrade, deny)