Erreurs et Limites de Taux

Format d'erreur

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

Codes d'erreur

Code	HTTP	Signification
`missing_api_key`	401	Aucune clé API fournie
`invalid_api_key`	401	Clé invalide/révoquée/inactive
`invalid_api_key_environment`	401	Environnement de clé (`live`/`test`) non activé sur ce gateway
`forbidden`	403	Portée insuffisante pour l'endpoint
`tier_required`	403	La fonctionnalité API nécessite le plan Team
`not_found`	404	Endpoint ou ressource non trouvé
`validation_error`	400	Corps, paramètres, géométrie ou IDs invalides
`idempotency_key_conflict`	409	Même `Idempotency-Key` utilisé avec un payload différent
`idempotency_in_progress`	409	Requête avec même `Idempotency-Key` encore en traitement
`rate_limit_exceeded`	429	Limite par minute (ou quota quotidien du plan) dépassé
`timeout`	504	L'export a expiré
`usage_service_unavailable`	503	Service d'utilisation/quota indisponible
`tier_check_unavailable`	503	Service de validation du plan indisponible
`internal_error`	500	Erreur serveur inattendue

Codes de statut HTTP utilisés

Statut	Signification
200	Succès
201	Créé
204	Supprimé sans corps
400	Erreur de validation
401	Non autorisé
403	Interdit
404	Non trouvé
409	Conflit/en cours d'idempotence
429	Limite de débit dépassée
500	Erreur interne
503	Service amont indisponible
504	Timeout

Limites de débit

Limite par minute par clé

Chaque clé a une limite par minute (par défaut 300 req/min, configurable par clé).

Exemple de réponse 429 :

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

Quota quotidien du plan

En plus des limites par minute, un quota quotidien au niveau du plan s'applique. S'il est atteint, l'API retourne 429 avec une indication de réessai de 24h.

Comportement d'idempotence

Pour les routes d'écriture utilisant POST et PUT :

Même Idempotency-Key + même payload : réponse mise en cache rejouée
Même clé + payload différent : 409 idempotency_key_conflict
Même clé pendant que la première requête est encore en traitement : 409 idempotency_in_progress

Les réponses rejouées incluent :

Idempotency-Replayed: true

Endpoints d'administration

GET /v1/organization

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

GET /v1/webhooks (portée admin)

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

Tableau de bord des opérations API (portée admin)

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