Toute erreur renvoie un statut 4xx ou 5xx et le même corps JSON, quelle que soit l'opération : un code stable, à tester dans votre code ; un message pour un humain, dans la langue d'Accept-Language (en, fr, es, it, de, pt), qui peut évoluer ; parfois des details.
Corps d'une erreur
{
"error": {
"code": "string",
"message": "string",
"details": "(facultatif)"
}
}Exemple : requête invalide
Réponse 400
{
"error": {
"code": "validation_error",
"message": "Certains champs sont invalides. Merci de vérifier votre saisie.",
"details": {
"target": "query",
"issues": [
{
"path": "department",
"message": "Invalid string: must match pattern /^(\\d{2}|2[AB])$/i"
}
]
}
}
}details.target dit où se trouve le problème (json pour le corps, query, param pour le chemin) ; details.issues liste chaque problème, avec path (le champ) et message (en anglais).
Les 23 codes
| HTTP | Code | Signification | Que faire |
|---|---|---|---|
400 | validation_error | Certains champs sont invalides. Merci de vérifier votre saisie. | Corriger la requête ; ne pas réessayer à l'identique |
400 | bad_request | Votre demande est incomplète ou mal formée. | Corriger la requête ; ne pas réessayer à l'identique |
400 | invalid_cursor | Ce curseur de pagination est invalide. Reprenez la liste depuis le début, sans « cursor ». | Reprendre la liste à la première page |
401 | invalid_api_key | Clé d'API absente ou invalide. Ajoutez l'en-tête « Authorization: Bearer fw_live_… ». | Corriger la requête ; ne pas réessayer à l'identique |
401 | api_key_revoked | Cette clé d'API a été révoquée. Demandez une nouvelle clé à contact@floweet.com. | Nous écrire (clé, scopes, compte d'API) |
403 | insufficient_scope | Cette clé d'API n'a pas le scope nécessaire à cette route. | Nous écrire (clé, scopes, compte d'API) |
403 | live_not_enabled | La production n'est pas encore ouverte pour ce compte : utilisez une clé fw_test_ ou demandez l'ouverture à contact@floweet.com. | Nous écrire (clé, scopes, compte d'API) |
403 | account_suspended | L'accès à l'API est suspendu pour ce compte. Écrivez à contact@floweet.com. | Nous écrire (clé, scopes, compte d'API) |
403 | account_misconfigured | Le compte d'API de cette organisation est mal configuré (membre désigné absent). Écrivez à contact@floweet.com. | Nous écrire (clé, scopes, compte d'API) |
403 | plan_required | Ce module n'est pas inclus dans l'offre de votre organisation. | Le module n'est pas dans l'offre de l'organisation : changer d'offre |
404 | not_found | Cette ressource est introuvable. | Corriger la requête ; ne pas réessayer à l'identique |
404 | sirene_not_found | Établissement introuvable dans l'annuaire SIRENE. | Corriger la requête ; ne pas réessayer à l'identique |
409 | idempotency_in_progress | Une requête avec la même clé d'idempotence est en cours. Réessayez dans un instant. | Réessayer après Retry-After (ou quelques secondes) |
422 | idempotency_key_mismatch | Cette clé d'idempotence a déjà servi pour une requête différente (méthode, chemin ou corps). Utilisez une nouvelle clé. | Corriger la requête ; ne pas réessayer à l'identique |
422 | prospect_limit | Vous avez atteint la limite de 200 prospects. Supprimez-en avant d'en ajouter. | Supprimer des prospects avant d'en créer |
429 | rate_limited | Vous avez envoyé trop de requêtes. Merci de réessayer dans un instant. | Réessayer après Retry-After (ou quelques secondes) |
429 | test_quota_exceeded | Quota du bac à sable atteint (1 000 appels par jour avec une clé fw_test_). Réessayez demain. | Réessayer après Retry-After (ou quelques secondes) |
500 | internal_error | Une erreur inattendue est survenue. Merci de réessayer. | Réessayer avec un délai croissant et la même Idempotency-Key |
500 | database_error | Les données n'ont pas pu être lues ou enregistrées. Merci de réessayer. | Réessayer avec un délai croissant et la même Idempotency-Key |
502 | geocode_unavailable | Géocodage momentanément indisponible. | Réessayer avec un délai croissant et la même Idempotency-Key |
502 | route_unavailable | Calcul d'itinéraire momentanément indisponible. | Réessayer avec un délai croissant et la même Idempotency-Key |
502 | upstream_error | Un service partenaire ne répond pas. Merci de réessayer dans un instant. | Réessayer avec un délai croissant et la même Idempotency-Key |
503 | unavailable | Ce service est momentanément indisponible. Merci de réessayer dans un instant. | Réessayer après Retry-After (ou quelques secondes) |
De nouveaux codes peuvent apparaître pour de nouveaux cas : traitez un code inconnu selon son statut HTTP.
Ce que portent les détails
insufficient_scope:details.required(le scope exigé) etdetails.granted(ceux de la clé) — voir les scopes.plan_required:details.moduleetdetails.tier(l'offre minimale) — voir offres et IA.rate_limitedettest_quota_exceeded:details.retryAfter, en secondes, comme l'en-têteRetry-After.
Réessayer sans risque
- 4xx : ne réessayez pas à l'identique, corrigez d'abord — sauf
429(attendezRetry-After) et409 idempotency_in_progress(réessayez dans une seconde). - 500, 502, 503, délai dépassé ou connexion coupée : réessayez avec un délai croissant (1 s, 5 s, 30 s…), avec la même
Idempotency-Key. Vous ne savez pas si la première requête a abouti ; la clé garantit qu'elle ne s'exécute qu'une fois (idempotence). - Citez l'en-tête
X-Request-Idde la réponse si vous nous écrivez : il retrouve votre requête dans nos journaux.