Menu
Thème
Ouvrir la console
APIVersion de l’API v1
Ouvrir la consoleEnglish

Codes d’erreur

Chaque code que l’API peut renvoyer : ce qu’il signifie et ce qu’il faut faire.

L’objet error

Le corps de toute réponse d’erreur : un objet error.

Attributs

errorobject
L’erreur.
Attributs enfants
typeenum
La famille de l’erreur. Une liste fermée : une nouvelle valeur est annoncée dans le journal des changements.
Valeurs possibles
  • invalid_request_error
  • authentication_error
  • permission_error
  • rate_limit_error
  • api_error
codeenum
Le code de l’erreur, stable : fiez-vous à lui. Une liste fermée ; l’ajout d’un code est une évolution compatible, un client doit donc accepter un code qu’il ne connaît pas (et s’en tenir au statut HTTP).
Valeurs possibles
  • parameter_invalid
  • parameter_missing
  • parameter_unknown
  • search_query_invalid
  • api_key_invalid
  • plan_feature_missing
  • api_key_scope_missing
  • resource_missing
  • route_missing
  • organization_suspended
  • api_error
  • service_unavailable
  • rate_limit_exceeded
messagestring
Une explication en anglais pour un développeur. Elle peut changer : ne vous y fiez jamais et ne la montrez jamais telle quelle à un utilisateur final.
paramstringpeut être null
Le paramètre de la requête en cause (son nom public, comme limit ou starting_after) ; null si aucun paramètre n’est en cause.
doc_urlstring
La page de la documentation qui explique le code.
request_idstring
L’identifiant de la requête, aussi dans l’en-tête Request-Id : communiquez-le au support.
Exemple d’erreur
{
  "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"
  }
}

Types d’erreur

invalid_request_error
La requête elle-même est incorrecte : un paramètre est invalide, manquant ou inconnu, la requête de recherche est mal formée, ou l’objet ou la route n’existe pas. Corrigez la requête avant de la renvoyer : la même requête échouera de la même façon.
authentication_error
La clé d’API n’a pas pu être utilisée : elle est absente, mal formée, inconnue, révoquée ou expirée. Vérifiez l’en-tête Authorization et la clé dans la console.
permission_error
La clé est valide, mais cet appel n’est pas autorisé : il manque un droit, l’offre n’inclut pas la fonctionnalité, ou l’organisation est suspendue. Renvoyer la requête n’y changera rien tant que la clé, l’offre ou l’organisation n’a pas changé.
rate_limit_error
Trop de requêtes pour cette clé d’API en peu de temps. Patientez, puis réessayez en espaçant les tentatives.
api_error
Un problème est survenu du côté de la plateforme, pas dans votre requête. Réessayez plus tard en espaçant les tentatives, et communiquez le request_id au support si le problème persiste.

Codes

parameter_invalid

Paramètre invalide

Statut HTTP
400

Quand cela arrive

Un paramètre a une valeur que l’opération n’accepte pas : un limit hors de l’intervalle 1 à 100 (ou supérieur à 20 avec expand[]), un id mal formé, un curseur inconnu, un champ qui ne peut pas être développé, starting_after et ending_before envoyés ensemble, un paramètre non répétable envoyé deux fois, ou un en-tête Accept qui exclut application/json. param nomme le paramètre en cause.

Que faire

Lisez param et message, corrigez cette valeur et renvoyez la requête. Vérifiez le paramètre dans la référence de l’opération.

Opérations qui peuvent le renvoyer

Exemple d’erreur
{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "message": "Invalid header 'Accept': this API answers application/json only.",
    "param": "Accept",
    "doc_url": "https://developer.masterconf.com/errors/codes#parameter_invalid",
    "request_id": "req_01JAZ5Q3X8M4K2N7P9R6T0V1W3"
  }
}

parameter_missing

Paramètre manquant

Statut HTTP
400

Quand cela arrive

Un paramètre obligatoire est absent, comme event pour lister les inscriptions, call_for_papers pour lister les communications, ou query pour une recherche. param le nomme.

Que faire

Ajoutez le paramètre nommé par param et renvoyez la requête.

Opérations qui peuvent le renvoyer

Exemple d’erreur
{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_missing",
    "message": "Missing required parameter 'event'.",
    "param": "event",
    "doc_url": "https://developer.masterconf.com/errors/codes#parameter_missing",
    "request_id": "req_01JAZ5Q3X8M4K2N7P9R6T0V1W3"
  }
}

parameter_unknown

Paramètre inconnu

Statut HTTP
400

Quand cela arrive

La requête contient un paramètre de requête que l’opération n’accepte pas. L’API n’en ignore jamais un en silence : un filtre mal orthographié renverrait sinon des données non filtrées. Le message liste les paramètres que l’opération accepte.

Que faire

Retirez le paramètre, ou corrigez son orthographe d’après la liste donnée dans message.

Opérations qui peuvent le renvoyer

Exemple d’erreur
{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_unknown",
    "message": "Unknown parameter 'sort' (this route takes no parameter).",
    "param": "sort",
    "doc_url": "https://developer.masterconf.com/errors/codes#parameter_unknown",
    "request_id": "req_01JAZ5Q3X8M4K2N7P9R6T0V1W3"
  }
}

search_query_invalid

Requête de recherche invalide

Statut HTTP
400

Quand cela arrive

La query d’une recherche est mal formée : un champ inconnu, un champ utilisé deux fois, un opérateur autre que : et ~, OR, une valeur sans guillemets simples, ou une valeur de ~ de moins de 3 caractères. Le message indique la position du problème.

Que faire

Corrigez la requête à la position indiquée dans message. Les clauses s’écrivent field:'value' ou field~'value', reliées par AND .

Opérations qui peuvent le renvoyer

Exemple d’erreur
{
  "error": {
    "type": "invalid_request_error",
    "code": "search_query_invalid",
    "message": "unknown field 'email' at position 53",
    "param": "query",
    "doc_url": "https://developer.masterconf.com/errors/codes#search_query_invalid",
    "request_id": "req_01JAZ5Q3X8M4K2N7P9R6T0V1W3"
  }
}

api_key_invalid

Clé d’API invalide

Statut HTTP
401

Quand cela arrive

L’en-tête Authorization est absent ou n’est pas exactement Bearer mcf_…, ou la clé est inconnue, révoquée ou expirée. Tous ces cas reçoivent la même réponse, volontairement. Une clé révoquée ou expirée est refusée dans les 60 secondes.

Que faire

Envoyez exactement Authorization: Bearer <key>, avec une clé de votre organisation. Si la clé a été révoquée ou a expiré, un administrateur en crée une nouvelle dans la console (« Intégrations »).

Opérations qui peuvent le renvoyer

Exemple d’erreur
{
  "error": {
    "type": "authentication_error",
    "code": "api_key_invalid",
    "message": "The API key is missing, malformed, unknown, revoked or expired.",
    "param": null,
    "doc_url": "https://developer.masterconf.com/errors/codes#api_key_invalid",
    "request_id": "req_01JAZ5Q3X8M4K2N7P9R6T0V1W3"
  }
}

plan_feature_missing

Non inclus dans l’offre

Statut HTTP
402

Quand cela arrive

L’offre de votre organisation n’inclut pas l’accès à l’API ou, pour les appels à communications et les communications, n’inclut pas le module des appels à communications.

Que faire

Demandez à un administrateur de votre organisation de changer d’offre. Renvoyer la requête n’y changera rien d’ici là.

Opérations qui peuvent le renvoyer

Exemple d’erreur
{
  "error": {
    "type": "permission_error",
    "code": "plan_feature_missing",
    "message": "The plan of your organization does not include access to the API.",
    "param": null,
    "doc_url": "https://developer.masterconf.com/errors/codes#plan_feature_missing",
    "request_id": "req_01JAZ5Q3X8M4K2N7P9R6T0V1W3"
  }
}

api_key_scope_missing

Droit manquant

Statut HTTP
403

Quand cela arrive

La clé est valide, mais il lui manque le droit dont l’opération a besoin (events_read, registrations_read ou calls_for_papers_read). Développer un événement demande aussi events_read. Le message nomme le droit manquant.

Que faire

Utilisez une clé qui a ce droit, ou demandez à un administrateur d’en créer une dans la console (« Intégrations »).

Opérations qui peuvent le renvoyer

Exemple d’erreur
{
  "error": {
    "type": "permission_error",
    "code": "api_key_scope_missing",
    "message": "This API key lacks the scope 'events_read'.",
    "param": null,
    "doc_url": "https://developer.masterconf.com/errors/codes#api_key_scope_missing",
    "request_id": "req_01JAZ5Q3X8M4K2N7P9R6T0V1W3"
  }
}

resource_missing

Objet introuvable

Statut HTTP
404

Quand cela arrive

Aucun objet de votre organisation n’a cet id : il n’existe pas, il a été supprimé, ou il appartient à une autre organisation. param nomme le paramètre qui portait l’identifiant.

Que faire

Vérifiez l’id. Si vous conservez des identifiants dans votre propre système, considérez que l’objet n’existe plus.

Opérations qui peuvent le renvoyer

Exemple d’erreur
{
  "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"
  }
}

route_missing

Route introuvable

Statut HTTP
404

Quand cela arrive

Le chemin ne correspond à aucune opération de l’API, par exemple à cause d’une faute de frappe. Aucune opération ne liste ce code : n’importe quelle requête peut le recevoir.

Que faire

Vérifiez le chemin dans la référence. Toutes les opérations de l’API sont des GET sous /v1.

Opérations qui peuvent le renvoyer

Lié à aucune opération : n’importe quelle requête peut le recevoir.

organization_suspended

Organisation suspendue

Statut HTTP
423

Quand cela arrive

Votre organisation est suspendue sur la plateforme. Tant qu’elle l’est, tout appel fait avec l’une de ses clés reçoit cette réponse.

Que faire

Contactez le support de la plateforme. Les appels fonctionnent de nouveau, avec les mêmes clés, dès que l’organisation est réactivée.

Opérations qui peuvent le renvoyer

Exemple d’erreur
{
  "error": {
    "type": "permission_error",
    "code": "organization_suspended",
    "message": "The organization is suspended.",
    "param": null,
    "doc_url": "https://developer.masterconf.com/errors/codes#organization_suspended",
    "request_id": "req_01JAZ5Q3X8M4K2N7P9R6T0V1W3"
  }
}

rate_limit_exceeded

Limite de débit dépassée

Statut HTTP
429

Quand cela arrive

La clé a envoyé plus de requêtes que sa limite de débit ne le permet. La limite est comptée par clé d’API par la passerelle placée devant l’API, sur des fenêtres fixes d’une minute ; elle est actuellement de 600 requêtes par minute. La réponse porte les en-têtes X-RateLimit-Limit, X-RateLimit-Remaining et X-RateLimit-Reset. La requête n’a jamais atteint l’API : le request_id du corps vaut donc null.

Que faire

Attendez le nombre de secondes indiqué par X-RateLimit-Reset, puis réessayez en espaçant les tentatives de façon exponentielle. Étalez les grosses synchronisations dans le temps plutôt que de les envoyer d’un bloc. Un 429 peut aussi venir de la protection de la passerelle contre les rafales par adresse IP, qui n’envoie pas d’en-têtes X-RateLimit-* : fiez-vous au statut et espacez vos tentatives de la même façon.

Opérations qui peuvent le renvoyer

Renvoyé par la passerelle placée devant l’API, avant que la requête n’atteigne une opération.

api_error

Erreur interne

Statut HTTP
500

Quand cela arrive

Une erreur inattendue s’est produite sur la plateforme pendant le traitement de la requête.

Que faire

Réessayez plus tard en espaçant les tentatives de façon exponentielle. Si l’erreur persiste, communiquez le request_id (ou l’en-tête Request-Id) au support.

Opérations qui peuvent le renvoyer

Exemple d’erreur
{
  "error": {
    "type": "api_error",
    "code": "api_error",
    "message": "An unexpected error occurred. Quote the request id to the support.",
    "param": null,
    "doc_url": "https://developer.masterconf.com/errors/codes#api_error",
    "request_id": "req_01JAZ5Q3X8M4K2N7P9R6T0V1W3"
  }
}

service_unavailable

Service indisponible

Statut HTTP
503

Quand cela arrive

Un service de la plateforme n’a pas pu être joint pendant le traitement de la requête. La réponse porte toujours un en-tête Retry-After, en secondes.

Que faire

Attendez le nombre de secondes indiqué par Retry-After, puis renvoyez la même requête. Espacez les tentatives si elle échoue de nouveau.

Opérations qui peuvent le renvoyer

Exemple d’erreur
{
  "error": {
    "type": "api_error",
    "code": "service_unavailable",
    "message": "A service of the platform could not be reached: try again shortly.",
    "param": null,
    "doc_url": "https://developer.masterconf.com/errors/codes#service_unavailable",
    "request_id": "req_01JAZ5Q3X8M4K2N7P9R6T0V1W3"
  }
}