Parcourir la documentation
Référence API
Identifiez la cause d’une requête en échec et décidez s’il faut la corriger, attendre ou réessayer.
Sur cette page
Codes de statut HTTP
Commencez par le statut HTTP, puis lisez le code et le message d’erreur pour connaître la cause précise.
| Statut | Signification | Action |
|---|---|---|
| 400 | Requête invalide | Corrigez la source, les champs obligatoires, les types des paramètres ou les en-têtes de réponse avant de réessayer. |
| 401 | Échec de l’authentification | Vérifiez X-API-Key. Remplacez une clé expirée ou révoquée ; réessayer avec la même clé ne résout pas le problème. |
| 402 | Crédits insuffisants | Vérifiez le solde du compte. Ajoutez des crédits ou laissez le propriétaire du compte résoudre l’accès avant de soumettre à nouveau. |
| 403 | Accès refusé | Vérifiez les permissions de la clé sur les sources et l’état du compte ou de l’abonnement. |
| 404 | Ressource introuvable | Vérifiez l’URL, l’identifiant de tâche et le compte. Les tâches en dehors du compte ou des sources autorisés peuvent aussi renvoyer 404. |
| 406 | Type de réponse non acceptable | Utilisez Accept: application/json ou text/plain. Sélectionnez Markdown avec X-Respond-With: markdown. |
| 409 | Résultat non prêt / conflit | Lors d’une lecture de résultat, vérifiez périodiquement la tâche existante jusqu’à sa fin. Pour les autres points d’accès, résolvez le conflit décrit dans le corps de la réponse. |
| 410 | Résultat expiré | Utilisez une copie enregistrée. Réessayer l’URL du résultat ne permet pas de restaurer un résultat expiré. |
| 422 | Entrée invalide / tâche en échec | Corrigez les champs signalés. Lors d’une lecture de résultat, inspectez job.error : une tâche en échec n’a pas de résultat réussi à récupérer. |
| 429 | Limite atteinte | Respectez Retry-After ou retry_after. Réduisez la fréquence des requêtes ; si la file d’attente est pleine, attendez la fin des tâches existantes. |
| 500 / 502 / 503 / 504 | Défaillance du service ou d’un fournisseur en amont | Réessayez les lectures avec des délais croissants et des limites de tentatives. Pour un POST ou un délai d’attente dépassé à la soumission, vérifiez si la tâche a été acceptée avant de renvoyer la requête. |
Lire une réponse d’erreur
Les erreurs API utilisent JSON, même si vous demandez du texte brut. Le corps varie selon le point d’accès. Adaptez le traitement au statut HTTP et au champ code lorsqu’il est présent ; utilisez message ou detail pour expliquer le problème.
Les erreurs de requête contiennent généralement error et message ; code est facultatif. Les erreurs d’authentification peuvent utiliser success: false au lieu de error: true.
{
"error": true,
"code": "unsupported_representation",
"message": "X-Respond-With supports markdown. Omit the header for the original result fields."
}Les réponses d’erreur V2 utilisent application/problem+json. Conservez requestId pour le support. Les erreurs de validation peuvent aussi inclure fieldErrors avec field, code et message.
{
"type": "https://api.flashdata.dev/problems/invalid_api_key",
"title": "Invalid API Key",
"status": 401,
"code": "invalid_api_key",
"requestId": "example-request-id",
"detail": "The API Key is invalid or unavailable."
}Inspecter le statut, les en-têtes et le corps
Utilisez curl --include pour voir les trois. Cet exemple vérifie votre clé avec une lecture gratuite du compte ; il ne soumet aucune requête de données. Définissez d’abord FLASHDATA_API_KEY dans votre environnement.
curl --include --silent --show-error --max-time 20 \
'https://api.flashdata.dev/v2/api-access/identity' \
--header "X-API-Key: ${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY}" \
--header 'Accept: application/json'Quand réessayer
Répéter un POST peut créer une nouvelle requête facturable. Un délai d’attente réseau dépassé ne prouve pas que la première requête a été rejetée. Enregistrez l’identifiant de tâche dès que vous le recevez.
| Situation | Action suivante |
|---|---|
| Entrée, clé, permission ou solde invalide | Arrêtez les tentatives. Corrigez la requête ou l’état du compte avant de réessayer ; ne bouclez pas sur ces erreurs. |
| 429 avec un délai d’attente indiqué | Respectez Retry-After, exprimé en secondes ou sous forme de date HTTP, ou la valeur JSON retry_after en secondes. Si les deux sont présents, utilisez le délai le plus long. |
| Requête de lecture : 429 / 5xx temporaire / erreur réseau | Réessayez le même GET. Sans délai indiqué, utilisez des délais croissants avec une variation aléatoire, un nombre maximal de tentatives et une limite de temps. |
| POST : délai d’attente dépassé ou 5xx ambigu | Conservez l’identifiant de tâche existant et vérifiez son état. Si vous n’avez reçu aucun identifiant, consultez l’historique des tâches avant de décider de soumettre à nouveau. |
Vérifier une tâche en arrière-plan
Un HTTP 200 sur le point d’accès d’état signifie que la lecture a réussi. Vérifiez job.status pour savoir si la tâche a réussi. Définissez JOB_ID avec l’identifiant de votre tâche existante ; cette commande n’en soumet pas une nouvelle.
| job.status | Action |
|---|---|
| pending / processing | Attendez, puis vérifiez à nouveau la même tâche. La lecture du résultat renvoie 409 jusqu’à la fin du traitement. |
| completed | Récupérez et enregistrez le résultat. Les résultats JSON d’origine renvoient une redirection 302 vers le stockage ; les résultats formatés renvoient directement un corps de réponse. |
| failed | Arrêtez les vérifications périodiques et inspectez job.error. Le point d’accès des résultats renvoie 422 avec le code result_not_ready pour une tâche en échec. |
curl --fail-with-body --silent --show-error --max-time 30 \
"https://api.flashdata.dev/v2/jobs/${JOB_ID:?Set JOB_ID}" \
--header "X-API-Key: ${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY}" \
--header 'Accept: application/json'Erreurs de format de réponse
| Statut / code | Correction |
|---|---|
| 400 · unsupported_representation | Définissez X-Respond-With sur markdown, ou supprimez cet en-tête. |
| 406 · not_acceptable | Définissez Accept sur application/json ou text/plain ; utilisez UTF-8 si vous indiquez un charset. |
Obtenir de l’aide sur une requête
Indiquez le point d’accès, l’horodatage UTC, le statut HTTP, le code d’erreur et l’identifiant de requête ou de tâche. Retirez du rapport les clés API, les jetons et les URL signées.