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
Sezione intitolata “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)
Sezione intitolata “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)
Sezione intitolata “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".
Visualizzazione degli attributi non valida (400)
Sezione intitolata “Visualizzazione degli attributi non valida (400)”La visualizzazione degli attributi di un livello viene
verificata prima di memorizzare qualsiasi cosa, nei caricamenti, nelle creazioni in linea e in
PATCH /api/layers/:layerId. Un valore che l’app non può usare viene rifiutato, con i motivi sotto forma
di codici di errore:
{ "error": "invalid_attribute_display", "details": ["classification.breaks_not_increasing", "classification.colors_length"] }Non viene memorizzato nulla, quindi correggi il valore e invia di nuovo la richiesta.
Limite di dimensione dei caricamenti (413)
Sezione intitolata “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)
Sezione intitolata “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
Sezione intitolata “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://app.collmap.com), che CORS consente con le intestazioni Authorization e
Content-Type.