Erreurs et limites

Les erreurs sont du JSON comportant un champ error (et souvent un code lisible par machine). Les messages sont assainis — URL, clés S3 et chemins de fichiers sont remplacés par [internal].

Codes de statut

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

Échecs transitoires qu’il vaut la peine de réessayer (502 / 503)

Les écritures qui modifient le document vivant d’une salle peuvent échouer pour des raisons qui ne sont la faute de personne et qui se résolvent d’elles-mêmes :

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

Le 503 peut être réessayé tel quel : la requête a été refusée avant de toucher quoi que ce soit, plutôt qu’appliquée aveuglément par-dessus un état que le serveur ne pouvait pas confirmer. Patientez brièvement et recommencez.

Jeton non autorisé (fermé par défaut)

Un jeton d’API de salle utilisé sur un point de terminaison hors de sa liste blanche :

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

Un jeton visant une autre salle, ou dépourvu de la permission requise, sur un point de terminaison autorisé renvoie un 403 simple avec une raison telle que "API token is not scoped to this room" ou "API token lacks '<perm>' permission".

Limite de taille d’import (413)

Tout envoi multipart unique de plus de 50 Mo est refusé (jamais un 500) :

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

Utilisez les points de terminaison d’envoi par blocs (ou le script d’import) pour les fichiers plus volumineux.

Quota de stockage (413 / 403)

Le stockage est imputé au propriétaire de la salle et vérifié avant que le moindre octet ne soit persisté :

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

kind: "storage_total" correspond à un 413 ; les plafonds de nombre de salles imposés par un administrateur renvoient un 403 avec kind: "room_count". Libérez de l’espace (supprimez des données) ou passez à un forfait supérieur.

Limitation de débit et CORS

Les surfaces publiques limitées en débit (comme les tuiles de carte) appliquent des limites par IP et renvoient un 429 avec un en-tête Retry-After en cas de dépassement ; les clients doivent alors patienter. Les écritures de repères et de commentaires sont également limitées par appelant — un traitement en lot devrait se cadencer plutôt que s’exécuter en boucle serrée. Les clients navigateur sont servis depuis l’origine de l’application (https://collmap.com), que CORS autorise avec les en-têtes Authorization et Content-Type.