Gérer les erreurs

L’API utilise les codes de statut HTTP : 2xx en cas de succès, 4xx pour un problème dans la requête, 5xx pour un problème du côté de la plateforme. Toutes les erreurs ont le même corps JSON.

L’objet error

{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_missing",
    "message": "No such event: 'EVT-5a1f0c2e-3b7d-4e91-9c2a-1d6e8f4b7a30'.",
    "param": "id",
    "doc_url": "https://developer.masterconf.com/errors/codes#resource_missing",
    "request_id": "req_01JAZ5Q3X8M4K2N7P9R6T0V1W3"
  }
}

• type : la famille de l’erreur. Cinq valeurs, détaillées plus bas.
• code : la raison précise, comme resource_missing. Stable : fiez-vous à lui.
• message : une explication en anglais, pour un développeur. Elle peut changer : ne vous y fiez jamais et ne la montrez pas telle quelle à vos propres utilisateurs.
• param : le paramètre en cause, comme limit ou starting_after, ou null.
• doc_url : la page du code dans cette documentation.
• request_id : l’identifiant de la requête, à communiquer au support. Voir Identifiants de requête.

La page des codes d’erreur détaille chaque code : ce qu’il signifie et ce qu’il faut faire.

Type et code

Le type vous dit comment réagir ; le code vous dit exactement ce qui s’est passé.

• invalid_request_error (400, 404) : la requête est incorrecte. Corrigez-la avant de la renvoyer ; la même requête échouera de la même façon.
• authentication_error (401) : la clé n’a pas pu être utilisée. Vérifiez l’en-tête Authorization et la clé.
• permission_error (402, 403, 423) : la clé est valide, mais l’appel n’est pas autorisé : un droit, l’offre ou une organisation suspendue. Réessayer n’y change rien tant que cela ne change pas.
• rate_limit_error (429) : trop de requêtes. Patientez, puis réessayez. Voir Limites de débit.
• api_error (500, 503) : la plateforme a échoué. Réessayez plus tard.

De nouveaux codes peuvent apparaître au sein de v1. Face à un code que vous ne connaissez pas, fiez-vous au statut HTTP et au type.

Réessayer

Ne réessayez que ce qui peut réussir plus tard :

• 500 api_error et 503 service_unavailable : réessayez en espaçant les tentatives de façon exponentielle. Une 503 porte un en-tête Retry-After : attendez au moins ce nombre de secondes.
• 429 rate_limit_exceeded : attendez le délai indiqué par X-RateLimit-Reset, puis réessayez.

Ne renvoyez jamais telle quelle une autre erreur 4xx. Chaque opération est un GET qui ne modifie rien : réessayer est donc toujours sans risque.

Routes inconnues

Un GET vers un chemin sous /v1/ qui ne correspond à aucune opération renvoie 404 route_missing, avec l’objet error habituel.

Une requête qui n’est ni un GET ni un HEAD, ou dont le chemin est hors de /v1/, ne reçoit pas de réponse de cette API : sa réponse ne porte pas cet objet error.