Erreurs et limites de débit

L'API utilise les codes HTTP standards. Toute erreur renvoie un objet JSON avec au minimum une clé message, rédigée en français et affichable telle quelle à l'utilisateur dans la plupart des cas.

Récapitulatif#

401 : non authentifié#

{ "message": "Unauthenticated." }

Envoyez bien Accept: application/json : sans cet en-tête, une requête non authentifiée peut être redirigée vers une page de connexion au lieu de recevoir ce 401.

402 : limite de la formule#

Renvoyé quand l'action dépasse ce que permet la formule du compte. La clé upgrade vaut toujours true : c'est le signal pour afficher une proposition de changement de formule.

{ "message": "Votre formule ne permet pas de créer un site supplémentaire.", "upgrade": true }

Les limites de chaque formule sont renvoyées par GET /v1/plans et dans limits de GET /v1/me :

403 : interdit#

Compte suspendu (toutes les routes protégées) :

{ "message": "Votre compte est suspendu. Contactez hello@monsiteo.com." }

Ressource appartenant à un autre compte (site, page, domaine, message, média) :

{ "message": "This action is unauthorized." }

404 : introuvable#

Identifiant inexistant ou supprimé, ou route inconnue :

{ "message": "No query results for model [App\\Models\\Site] 999" }

Ne vous fiez pas au texte exact de ce message, seulement au code 404. POST /sites/{site}/domain/verify renvoie aussi 404 si aucun domaine n'est relié au site.

409 : conflit d'édition#

PATCH /v1/pages/{page} accepte un champ updated_at (la date de dernière modification que vous connaissez). Si la page a été enregistrée depuis par un autre appareil, la mise à jour est refusée :

{ "message": "Cette page a été modifiée depuis un autre appareil. Rechargez-la.", "conflict": true }

Rechargez la page (GET /v1/pages/{page}), réappliquez vos modifications sur la version à jour, puis renvoyez-la avec le nouveau updated_at. Pour écraser volontairement la version du serveur, renvoyez la requête sans updated_at. Détails : Pages.

422 : données invalides#

Format standard de validation : message résume la première erreur et errors liste les messages par champ (notation pointée pour les champs imbriqués).

{
  "message": "Cette adresse est déjà prise.",
  "errors": {
    "slug": ["Cette adresse est déjà prise."]
  }
}

{
  "message": "The theme.primary field format is invalid.",
  "errors": {
    "theme.primary": ["The theme.primary field format is invalid."],
    "settings.business.email": ["The settings.business.email field must be a valid email address."]
  }
}

Bon à savoir Les messages métier (adresse prise ou réservée, domaine invalide, page d'accueil non supprimable, identifiants incorrects...) sont rédigés en français. Les messages génériques de validation dépendent de la langue configurée sur le serveur : basez votre logique sur les noms de champs dans errors, pas sur le texte.

Quelques routes renvoient aussi 422 sans errors : POST /billing/checkout (« Formule inconnue ou non configurée dans Stripe. ») et POST /sites/{site}/media pour un SVG invalide (« Ce fichier SVG est invalide et a été refusé. »).

429 : trop de requêtes#

{ "message": "Too Many Attempts." }

Les réponses des routes limitées portent les en-têtes X-RateLimit-Limit et X-RateLimit-Remaining. Une réponse 429 ajoute Retry-After (en secondes) et X-RateLimit-Reset (horodatage Unix). Attendez ce délai avant de réessayer, idéalement avec un délai croissant.

Limites de débit#

Les compteurs sont calculés par utilisateur connecté, ou par adresse IP pour les routes publiques.

500 et 503#

Une erreur 500 signale un problème de notre côté : elle est journalisée et nous sommes alertés. Réessayez après quelques instants. Le 503 n'est utilisé que par le webhook Stripe quand le secret n'est pas configuré (voir Webhooks Stripe).