Troubleshooting

Every error response has a detail (a sentence, or an object with a code). Gateway errors also carry a trace_id, and every response has an X-Request-ID header — include it when you contact support. The full list of codes is in the HTTP API reference.

#The browser says CORS error, or the API returns 403 ORIGIN_NOT_ALLOWED

• Cause: the site's origin (scheme, host and port) isn't in the project's allowed origins. Local development on a port is only allowed if http://localhost:* is listed.
• Check: the browser's network tab shows the Origin request header; compare it with Project settings → API → Allowed origins.
• Fix: add the exact origin, or https://*.yourdomain.com for subdomains. See Allowed origins (CORS) for browser apps.

#401 right after signing in

• Cause: the session expired and wasn't refreshed, or the app is using a different project's URL or key.
• Check: the project URL and anon key both come from Connect for the same project.
• Fix: keep tokens across reloads as shown in Connect your app; sign in again if the refresh token was revoked.

#403 NO_POLICY_DEFINED or a policy denial on a table

• Cause: no access policy decides for the table and its row-level security isn't enabled and forced, or a policy denies this caller.
• Check: sov sim run --resource public.<table> shows which check stopped the request for each user type.
• Fix: follow Row-level security and access; then re-run the simulation.

#403 PLAN_LIMIT_REACHED, PLAN_QUOTA_EXHAUSTED or PLAN_FEATURE_REQUIRED

• Cause: the action needs a plan feature, or a limit or monthly quota is used up. The body names the limit_key, the current limit, used and the required_plan.
• Fix: upgrade, buy an add-on where one exists, or wait for resets_at. See Plans, usage and limits and Plan limits.

#429 RATE_LIMIT_EXCEEDED

• Cause: too many requests for the project or the caller.
• Fix: wait Retry-After seconds and retry with exponential backoff; cache reads that don't change often.

#409 IDEMPOTENCY_IN_PROGRESS

• Cause: a request with the same Idempotency-Key is still being processed.
• Fix: retry with the same key after a moment — the first request's result is returned, so nothing happens twice. The SDKs retry this for you.

#503 RESOURCE_BUSY or PROJECT_MAINTENANCE

• Cause: another change to the same thing is in progress, or the database is starting.
• Fix: retry after Retry-After seconds.

#The Staging first switch says it needs an upgrade

• Cause: environments aren't included in Free.
• Fix: see Environments, staging and deploying to production for plans and the extra-environment add-on.