Start with the HTTP status and structured error response, then verify the organization, service, plan, caller role, and external billing configuration.
Symptom guide
| Symptom | Check | Resolution |
|---|---|---|
| Service creation returns 400 | Organization service limit, slug uniqueness, and service type | Remove an unused service, request a limit change, choose a unique slug, or use a supported type |
| Management returns 401 | Bearer token and Authorization header | Obtain a current organization-management JWT |
| Update or plan mutation returns 403 | Caller membership and owner/admin role | Use a caller with the required organization role |
| Service or plan returns 404 | Organization slug, service slug, and plan ID | Load the parent resource first and use its canonical identifiers |
| Service deletion returns 400 | Active subscriptions | Cancel or migrate subscriptions before deletion |
| Plan deletion returns 400 | Active subscriptions on the plan | Migrate subscribers and confirm the active count is zero |
| OAuth callback fails after an update | Exact redirect URI and provider scopes | Register the production HTTPS callback and retest the provider flow |
| Checkout reports a missing price | Plan’s stripe_price_id |
Associate the correct test or live Stripe Price with the plan |
| Checkout returns 500 | Stripe credentials, webhook configuration, and environment mode | Verify server-side Stripe configuration without exposing secrets |
| Counts appear stale | Selected service and completed subscription lifecycle | Reload service details after the relevant asynchronous billing work completes |
Safe diagnostic sequence
- Reproduce with the smallest management request.
- Record the status,
error_code, and timestamp without recording credentials. - Confirm the organization is active and the caller has the documented role.
- Inspect the service or plan with a GET request before retrying a mutation.
- For checkout failures, compare AuthOS and Stripe environments and identifiers.
- Use API error handling for retry and logging patterns.