Errori e limiti

Gli errori sono JSON con un campo error (e spesso un codice leggibile dalla macchina). I messaggi sono ripuliti — URL, chiavi S3 e percorsi del filesystem vengono sostituiti con [internal].

Codici di stato

// 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" }

Guasti transitori per cui vale la pena riprovare (502 / 503)

Le scritture che modificano il documento dal vivo di una stanza possono fallire per motivi di cui non ha colpa nessuno e che si risolvono da soli:

// 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" }

Il 503 si può ripetere così com’è: la richiesta è stata rifiutata prima di toccare qualsiasi cosa, anziché applicata alla cieca sopra uno stato che il server non poteva confermare. Attendi un momento e riprova.

Token non consentito (fail-closed)

Un token API della stanza usato su un endpoint fuori dal suo elenco dei consentiti:

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

Un token rivolto a un’altra stanza, o privo del permesso richiesto, su un endpoint consentito restituisce un semplice 403 con una motivazione come "API token is not scoped to this room" oppure "API token lacks '<perm>' permission".

Limite di dimensione dei caricamenti (413)

Qualsiasi singolo caricamento multipart oltre i 50 MB viene rifiutato (mai con un 500):

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

Per i file più grandi usa gli endpoint di caricamento a blocchi (oppure lo script di importazione).

Quota di spazio (413 / 403)

Lo spazio viene addebitato al proprietario della stanza e verificato prima che venga memorizzato un solo byte:

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

kind: "storage_total" corrisponde a un 413; i limiti al numero di stanze imposti da un amministratore restituiscono 403 con kind: "room_count". Libera spazio (elimina dati) oppure passa a un piano più capiente.

Limitazione di frequenza e CORS

Le superfici pubbliche con limitazione di frequenza (come le tile della mappa) applicano limiti per IP e restituiscono 429 con un’intestazione Retry-After quando vengono superati; i client dovrebbero rallentare. Anche le scritture di segnaposto e commenti sono limitate per chiamante — un lavoro in batch dovrebbe darsi un ritmo invece di eseguire un ciclo serrato. I client browser sono serviti dall’origine dell’app (https://collmap.com), che CORS consente con le intestazioni Authorization e Content-Type.