Erreurs
Formats et codes d'erreur de l'API de réservation IA, des endpoints de gestion d'un rendez-vous, des endpoints publics des formulaires et du serveur MCP.
Vue d'ensemble
Nudge utilise les codes de statut HTTP standard. Le format du corps dépend de l'interface :
| Interface | Corps d'erreur |
|---|---|
| API de réservation IA | { "error": { "code": "…", "message": "…" } } |
| Gestion d'un rendez-vous | { "error": "code" } |
| Endpoints publics des formulaires | { "error": "Form not found" } |
| Serveur MCP | Erreur HTTP, erreur JSON-RPC, ou résultat d'outil avec isError: true |
Appuyez votre code sur le statut et le code, pas sur le message : les messages sont écrits pour des humains et peuvent être reformulés.
Pour ne pas révéler quels identifiants existent, Nudge donne souvent une seule réponse pour plusieurs causes : un rendez-vous inconnu et un mauvais jeton, par exemple, peuvent renvoyer la même erreur.
API de réservation IA
Chaque erreur a cette forme :
{ "error": { "code": "slot_taken", "message": "This slot has just been taken. Please pick another time." } }| Statut | code | Causes et messages typiques |
|---|---|---|
| 400 | bad_request | Paramètre manquant (Missing: org, form, slot_id, email, Missing short_id param…), Invalid JSON body, action inconnue, Form not found, Invalid slot_id, Invalid or tampered slot_id, Slot has expired; please refetch availability, Slot does not belong to this form, No available closers, plage de dates invalide |
| 400 | invalid_slot | Début ou fin illisible, ou fin avant le début |
| 400 | slot_in_past | Le créneau a déjà commencé |
| 400 | invalid_duration | Le créneau ne correspond pas à la durée du formulaire |
| 400 | outside_availability | Le créneau sort des horaires de travail de l'hôte |
| 400 | invalid_booking_data | Le formulaire, le contact ou l'hôte ne vont pas ensemble |
| 400 | booking_failed | La réservation n'a pas pu aboutir ; réessayez plus tard |
| 403 | forbidden | AI booking disabled for this form, Invalid cancellation token, Invalid reschedule token |
| 404 | not_found | Booking not found, Original booking not found |
| 409 | slot_taken | Quelqu'un a pris ce créneau entre-temps : relisez les disponibilités |
| 429 | rate_limited | Trop d'appels depuis votre IP, voir Limites de débit |
| 500 | internal_error | Erreur inattendue ; réessayez plus tard |
| 502 | calendar_failed | Le rendez-vous n'a pas pu être écrit dans l'agenda de l'hôte ; rien n'a été réservé |
| 503 | not_configured | L'API de réservation est momentanément indisponible |
Que faire
slot_taken,Slot has expired: rappelezget_availabilityet proposez un nouveau créneau à la personne.forbiddenavecAI booking disabled for this form: l'espace a désactivé la réservation IA sur ce formulaire. Ne réessayez pas.booking_failed,calendar_failed,internal_error,not_configured: réessayez plus tard avec la mêmeIdempotency-Key.
Gestion d'un rendez-vous
Les endpoints sous /api/booking/{bookingId} renvoient un code unique :
{ "error": "slot_unavailable" }| Statut | error | Endpoint | Signification |
|---|---|---|---|
| 400 | invalid_body | reschedule | Le corps n'est pas du JSON valide |
| 400 | slot_required | reschedule | start et end manquent ou ne sont pas des dates-heures ISO 8601 avec décalage |
| 400 | invalid_duration | reschedule | end - start diffère de la durée du rendez-vous |
| 400 | slot_in_past | reschedule | Le nouveau créneau a déjà commencé |
| 400 | too_soon | reschedule | Le nouveau créneau tombe dans le délai minimum du formulaire |
| 400 | too_far | reschedule | Le nouveau créneau dépasse la fenêtre de réservation du formulaire |
| 400 | reason_required | cancel | reason manque ou est vide |
| 403 | token_required | reschedule, cancel | Le jeton manque ou est faux |
| 403 | token_invalid | ics | Un jeton a été fourni et il est faux |
| 404 | not_found | tous | Identifiant de rendez-vous inconnu |
| 409 | not_reschedulable | slots, reschedule | Le rendez-vous n'est plus planifié, ou le formulaire n'autorise pas son déplacement |
| 409 | not_cancellable | cancel | Le rendez-vous n'est plus planifié, ou le formulaire n'autorise pas son annulation |
| 409 | not_scheduled | ics | Le rendez-vous a été annulé ou déplacé |
| 409 | slot_unavailable | reschedule | Le créneau n'est plus libre, ou n'était pas proposé pour ce rendez-vous |
| 429 | rate_limited | tous | Voir Limites de débit |
| 502 | availability_failed | slots | Les disponibilités n'ont pas pu être calculées |
| 502 | reschedule_failed | reschedule | Le nouveau rendez-vous n'a pas pu être créé ; l'original est intact |
| 502 | cancel_failed | cancel | L'annulation n'a pas abouti ; le rendez-vous tient toujours |
| 503 | availability_unavailable | reschedule | Les disponibilités n'ont pas pu être vérifiées ; le rendez-vous d'origine est intact |
Deux réponses de succès sont à connaître : {"alreadyCancelled": true} à l'annulation (rien à faire), et {"rescheduled": true, …} au déplacement.
Endpoints publics des formulaires
| Statut | Corps | Signification |
|---|---|---|
| 404 | {"error": "Form not found"} | Slugs inconnus, formulaire inactif ou espace suspendu |
Serveur MCP
Les erreurs peuvent survenir à trois niveaux.
HTTP, avant que la requête n'atteigne un outil :
| Statut | Corps | Signification |
|---|---|---|
| 401 | — (avec WWW-Authenticate) | Jeton absent ou invalide. Votre client doit lancer le parcours OAuth. |
| 403 | {"error": "Origin not allowed"} | Requête de navigateur depuis un site autre que l'application Nudge, Claude ou ChatGPT |
| 403 | {"error": "Account suspended"} | Votre compte Nudge est suspendu |
| 405 | — | GET avec un jeton : le serveur n'accepte que POST |
| 413 | {"error": "Request too large"} | Corps de plus de 12 Mo |
| 429 | {"error": "Rate limit exceeded"} | Plus de 60 requêtes par minute |
JSON-RPC, pour les messages mal formés :
| Code | Message |
|---|---|
-32700 | Parse error : le corps n'est pas du JSON valide |
-32600 | Invalid request, ou Batch requests are not supported |
-32601 | Method not found |
-32602 | Tool name is required |
Résultats d'outil, quand l'action elle-même refuse. L'appel réussit au niveau du protocole et le résultat porte isError: true avec un message lisible :
{
"jsonrpc": "2.0",
"id": 7,
"result": {
"isError": true,
"content": [{ "type": "text", "text": "Forbidden: bookings.cancel" }]
}
}Messages fréquents : Forbidden: <permission> (votre rôle n'a pas la permission), orgSlug is required, args must be an array of at most 8 items, Unknown tool: <name>, File exceeds 8 MB, et <tool> did not finish within 240 s (l'action peut encore aboutir ; vérifiez avant de réessayer).
Webhooks
Quand Nudge appelle votre webhook, le statut que vous renvoyez est enregistré dans les Journaux de livraison. Nudge ne retente pas les livraisons échouées ; voir Webhooks.