Fehler und Ratenlimits | Mapalyze API-Dokumentation

Fehlerformat

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

Fehlercodes

Code	HTTP	Bedeutung
`missing_api_key`	401	Kein API-Schlüssel angegeben
`invalid_api_key`	401	Schlüssel ungültig/widerrufen/inaktiv
`invalid_api_key_environment`	401	Schlüsselumgebung (`live`/`test`) auf diesem Gateway nicht aktiviert
`forbidden`	403	Scope reicht für den Endpoint nicht aus
`tier_required`	403	API-Funktion erfordert den Team-Plan
`not_found`	404	Endpoint oder Ressource nicht gefunden
`validation_error`	400	Ungültiger Body, Parameter, Geometrie oder IDs
`idempotency_key_conflict`	409	Gleicher `Idempotency-Key` mit anderem Payload verwendet
`idempotency_in_progress`	409	Anfrage mit gleichem `Idempotency-Key` wird noch verarbeitet
`rate_limit_exceeded`	429	Minutenlimit (oder tägliches Plan-Kontingent) überschritten
`timeout`	504	Export-Timeout
`usage_service_unavailable`	503	Nutzungs-/Kontingentservice nicht verfügbar
`tier_check_unavailable`	503	Plan-Validierungsservice nicht verfügbar
`internal_error`	500	Unerwarteter Serverfehler

Verwendete HTTP-Statuscodes

Status	Bedeutung
200	Erfolg
201	Erstellt
204	Gelöscht ohne Body
400	Validierungsfehler
401	Nicht autorisiert
403	Verboten
404	Nicht gefunden
409	Idempotenz-Konflikt/in Bearbeitung
429	Rate-Limit überschritten
500	Interner Fehler
503	Upstream-Service nicht verfügbar
504	Timeout

Rate-Limits

Pro-Schlüssel-Minutenlimit

Jeder Schlüssel hat ein Minutenlimit (Standard 300 req/min, pro Schlüssel konfigurierbar).

Beispiel für 429-Antwort:

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

Tägliches Plan-Kontingent

Zusätzlich zu den Minutenlimits gilt eine tägliche Kontingentbegrenzung auf Planebene. Bei Erreichen gibt die API 429 mit einem 24h-Wiederholungshinweis zurück.

Idempotenz-Verhalten

Für Schreibrouten mit POST und PUT:

Gleicher Idempotency-Key + gleicher Payload: gecachte Antwort wird wiedergegeben
Gleicher Schlüssel + anderer Payload: 409 idempotency_key_conflict
Gleicher Schlüssel während die erste Anfrage noch verarbeitet wird: 409 idempotency_in_progress

Wiedergegebene Antworten enthalten:

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