chore: update http error codes (#27775)

* chore: update http error codes

* chore: add note about dashboard access

* chore: mention status code 402 explicitly to not leave ambiguity

* Update apps/docs/content/guides/platform/http-status-codes.mdx

Co-authored-by: Charis <26616127+charislam@users.noreply.github.com>

* Update apps/docs/content/guides/platform/http-status-codes.mdx

Co-authored-by: Charis <26616127+charislam@users.noreply.github.com>

* Update apps/docs/content/guides/platform/http-status-codes.mdx

Co-authored-by: Charis <26616127+charislam@users.noreply.github.com>

* Update apps/docs/content/guides/platform/billing-faq.mdx

Co-authored-by: Charis <26616127+charislam@users.noreply.github.com>

* Update apps/docs/content/guides/platform/http-status-codes.mdx

Co-authored-by: Charis <26616127+charislam@users.noreply.github.com>

* fix: correct typo

---------

Co-authored-by: Charis <26616127+charislam@users.noreply.github.com>

apps/docs/content/guides/platform/billing-faq.mdx

@@ -116,7 +116,7 @@ The Fair Use Policy is applied through service restrictions. This could mean:
 - Pausing projects
 - Switching databases to read-only mode
 - Disabling new project launches/transfers
-- Responding with a 402 status code for all API requests
+- Responding with a [402 status code](/docs/guides/platform/http-status-codes#402-service-restriction) for all API requests
 
 The Fair Use Policy is generally applied to all projects of the restricted organization.
 

apps/docs/content/guides/platform/http-status-codes.mdx

@@ -18,6 +18,17 @@ The Supabase platform offers several HTTP APIs for each project. These APIs can
 
 4XX status codes indicate an issue on the client's end with the request being made. These could include missing or invalid auth information, a malformed request, making too many requests in too short a time period ("rate limiting"), or a network issue on the client's end.
 
+### 402 service restriction
+
+In case the Fair Use Policy is applied, the projects of your organization may be restricted from processing requests. If service restrictions are applied, projects will return a 402 status code together with a description of why the project is restricted. The description can contain one or more of the following codes:
+
+- `exceeded_*` indicates that the project has continued to exceeded the usage limits of its quota, e.g. `exceed_egress_quota`, `exceed_db_size_quota`.
+- `overdue_payment` indicates that the organization has overdue bills.
+
+You will still have access to your data through the Supabase dashboard when the Fair Use Policy is applied.
+
+See the [Fair Use Policy](/docs/guides/platform/billing-faq#fair-use-policy) section to learn more about the restrictions and how to remove them.
+
 ## 5XX server or project errors
 
 5XX status codes indicate that the project was unable to process the request successfully, but not because of an issue with the client's request.

apps/studio/components/interfaces/Organization/BillingSettings/Restriction.tsx

@@ -88,7 +88,8 @@ export const Restriction = () => {
                 {dayjs(org.restriction_data['grace_period_end']).format('DD MMM, YYYY')}
               </span>
               . After that, the Fair Use Policy will apply. If you plan to maintain this level of
-              usage, upgrade your plan to avoid any restrictions.
+              usage, upgrade your plan to avoid any restrictions. If restrictions are applied,
+              requests to your projects will return a 402 status code.
             </p>
             <div className="flex items-center gap-x-2 mt-3">
               <Button asChild key="upgrade-button" type="default">
@@ -114,7 +115,8 @@ export const Restriction = () => {
                 {dayjs(org.restriction_data['grace_period_end']).format('DD MMM, YYYY')}
               </span>
               . Fair Use Policy applies now. Stay below your plan’s quota or upgrade your plan if
-              you expect to exceed it.
+              you expect to exceed it. If you exceed your quota, requests will respond with a 402
+              status code.
             </p>
             <div className="flex items-center gap-x-2 mt-3">
               <Button key="upgrade-button" asChild type="default">
@@ -136,7 +138,8 @@ export const Restriction = () => {
           <AlertDescription_Shadcn_>
             <p>
               Fair Use Policy applies and your service is restricted. Your projects are not able to
-              serve requests. You have exceeded your plan’s quota and your grace period ended on{' '}
+              serve requests and will respond with a 402 status code. You have exceeded your plan’s
+              quota and your grace period ended on{' '}
               <span className="text-foreground">
                 {dayjs(org.restriction_data['grace_period_end']).format('DD MMM, YYYY')}
               </span>