Errors & Rate Limits

Error format

{
  "ok": false,
  "error": {
    "code": "error_code",
    "message": "Human-readable description"
  }
}

Error codes

Code	HTTP	Meaning
`missing_api_key`	401	No API key was provided
`invalid_api_key`	401	Key invalid/revoked/inactive
`invalid_api_key_environment`	401	Key environment (`live`/`test`) not enabled on this gateway
`forbidden`	403	Scope is insufficient for the endpoint
`tier_required`	403	API feature requires Team tier
`not_found`	404	Endpoint or resource not found
`validation_error`	400	Invalid body, params, geometry, or IDs
`idempotency_key_conflict`	409	Same `Idempotency-Key` used with a different payload
`idempotency_in_progress`	409	Request with same `Idempotency-Key` still processing
`rate_limit_exceeded`	429	Minute limit (or daily plan quota) exceeded
`timeout`	504	Export timed out
`usage_service_unavailable`	503	Usage/quota service unavailable
`tier_check_unavailable`	503	Tier validation service unavailable
`internal_error`	500	Unexpected server error

HTTP statuses used

Status	Meaning
200	Success
201	Created
204	Deleted with no body
400	Validation error
401	Unauthorized
403	Forbidden
404	Not found
409	Idempotency conflict/in-progress
429	Rate limit exceeded
500	Internal error
503	Upstream service unavailable
504	Timeout

Rate limits

Per-key minute limit

Each key has a per-minute limit (default 300 req/min, configurable per key).

429 response example:

{
  "ok": false,
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit of 300 requests/minute exceeded. Retry after 27 seconds.",
    "retry_after": 27
  }
}

Daily plan quota

In addition to per-minute limits, plan-level daily quota enforcement applies. If reached, the API returns 429 with a 24h retry hint.

Idempotency behavior

For write routes using POST and PUT:

Same Idempotency-Key + same payload: cached response replayed
Same key + different payload: 409 idempotency_key_conflict
Same key while first request still processing: 409 idempotency_in_progress

Replay responses include:

Idempotency-Replayed: true

Admin endpoints

GET /v1/organization

curl -H "X-API-Key: mk_live_..." \
  "https://<ref>.supabase.co/functions/v1/api-gateway/v1/organization"

GET /v1/webhooks (admin scope)

curl -H "X-API-Key: mk_live_..." \
  "https://<ref>.supabase.co/functions/v1/api-gateway/v1/webhooks"

API operations dashboard (admin scope)

GET /v1/api/metrics
GET /v1/api/reliability
GET /v1/api/alerts
POST /v1/api/alerts/run
POST /v1/api/alerts/:id/ack
GET /v1/api/key-lifecycle-alerts
POST /v1/api/key-lifecycle-alerts/run
POST /v1/api/key-lifecycle-alerts/:id/ack