Fehler & Grenzen

Fehler sind JSON mit einem Feld error (und oft einem maschinenlesbaren Code). Die Meldungen sind bereinigt — URLs, S3-Schlüssel und Dateipfade werden durch [internal] ersetzt.

Statuscodes

// 400 Bad Request
{ "error": "Missing required field: email" }

// 401 Unauthorized
{ "error": "Invalid or missing token" }

// 403 Forbidden
{ "error": "You do not have permission to perform this action", "required": "owner", "current": "editor" }

// 404 Not Found
{ "error": "Room not found" }

// 500 Internal Server Error
{ "error": "Internal server error" }

Vorübergehende Fehler, die ein erneuter Versuch lohnt (502 / 503)

Schreibvorgänge, die das lebende Dokument eines Raums verändern, können aus Gründen scheitern, an denen niemand schuld ist und die sich von selbst erledigen:

// 502 — the change could not be applied to the live room document
{ "error": "Failed to update marker" }

// 503 — the room's state was momentarily unreadable; nothing was changed
{ "error": "Room state temporarily unavailable" }

Ein 503 lässt sich unverändert wiederholen: Die Anfrage wurde abgelehnt, bevor irgendetwas berührt wurde, statt blind auf einen Zustand angewandt zu werden, den der Server nicht bestätigen konnte. Kurz abwarten und erneut senden.

Token nicht erlaubt (fail-closed)

Ein Raum-API-Token, das an einem Endpunkt außerhalb seiner Positivliste verwendet wird:

{ "error": "api_token_not_allowed",
  "message": "API tokens cannot access this endpoint. Tokens are limited to room-scoped data operations." }

Ein Token für einen anderen Raum oder ohne die nötige Berechtigung liefert an einem erlaubten Endpunkt ein schlichtes 403 mit einer Begründung wie "API token is not scoped to this room" oder "API token lacks '<perm>' permission".

Grenze der Uploadgröße (413)

Jeder einzelne Multipart-Upload über 50 MB wird abgelehnt (nie mit einem 500):

{ "error": "file_too_large", "maxBytes": 52428800,
  "message": "File exceeds the 50 MB single-request limit. Use the chunked endpoints for larger files." }

Nutzen Sie für größere Dateien die Endpunkte für den stückweisen Upload (oder das Import-Skript).

Speicherkontingent (413 / 403)

Der Speicher wird dem Raumeigentümer zugerechnet und geprüft, bevor Bytes dauerhaft abgelegt werden:

{ "error": "quota_exceeded", "kind": "storage_total",
  "limit": 10737418240, "current": 10500000000, "attempted": 300000000,
  "message": "Storage limit exceeded for this account" }

kind: "storage_total" ist ein 413; von Admins gesetzte Obergrenzen für die Anzahl der Räume liefern 403 mit kind: "room_count". Schaffen Sie Platz (Daten löschen) oder wechseln Sie in einen größeren Tarif.

Ratenbegrenzung und CORS

Öffentliche, ratenbegrenzte Oberflächen (etwa Kartenkacheln) wenden Grenzen je IP an und liefern bei Überschreitung 429 mit einem Header Retry-After; Clients sollten dann zurückstecken. Auch Schreiben von Markern und Kommentaren ist je Aufrufer begrenzt — Stapelarbeit sollte sich takten statt in einer engen Schleife zu feuern. Browser-Clients werden vom Ursprung der App (https://collmap.com) ausgeliefert, den CORS mit den Headern Authorization und Content-Type zulässt.