Référence

Erreurs & debugging

Toutes les erreurs AfriMap suivent un format JSON uniforme. Ce guide couvre chaque code d'erreur, les causes courantes et les solutions.

Format d'erreur uniforme

Chaque réponse d'erreur suit exactement cette structure, quel que soit l'endpoint :

JSONStructure d'erreur

 { "error": { "code": 400, "message": "invalid origin: lat must be between -90 and 90", "details": [ { "field": "origin.lat", "reason": "out_of_range", "value": 999.0 } ] } }

Champ	Type	Description
error.code	integer	Code HTTP (400, 401, 403, 404, 429, 500, 502, 503)
error.message	string	Message humain en anglais décrivant le problème
error.details	array \| null	Détails par champ pour les erreurs de validation (optionnel)

Codes d'erreur HTTP

400

Bad Request

La requête est malformée ou contient des valeurs invalides.

Causes courantes :

Coordonnées hors limites (lat: -90..90, lng: -180..180)
Champ obligatoire manquant (origin, destination)
Format invalide (polyline mal encodée, JSON cassé)
Mode de transport inconnu (utilisez auto, bicycle, pedestrian)

Solution : Vérifiez les paramètres de votre requête. Le champ details indique exactement quel paramètre pose problème.

401

Unauthorized

Clé API manquante ou invalide.

Causes courantes :

Header X-AfriMap-Key absent
Clé qui ne commence pas par afm_test_ ou afm_live_
Clé révoquée ou régénérée (l'ancienne n'est plus valide)
Faute de frappe dans la clé

Solution : Vérifiez que le header est bien présent et que la clé est correcte. Copiez-la directement depuis le Dashboard.

TerminalVérification rapide

# Testez votre clé avec un appel simple curl -s -o /dev/null -w "%{http_code}" \ -H "X-AfriMap-Key: VOTRE_CLE" \ https://api.afrimap.ci/v1/health

403

Forbidden

Votre clé est valide mais n'a pas accès à cette ressource.

Causes courantes :

Origine CORS non autorisée pour cette clé
Endpoint admin appelé avec une clé utilisateur
Compte suspendu pour impayé

404

Not Found

Ressource introuvable. L'endpoint existe mais l'identifiant demandé (place_id, operationId) ne correspond à rien. Vérifiez l'URL et les paramètres. Notez que tous les endpoints commencent par /v1/.

429

Too Many Requests

Quota dépassé. Consultez les headers X-RateLimit-* et Retry-After.

Solution : Implémentez un backoff exponentiel (voir guide authentification), ou passez à un plan supérieur.

500

Internal Server Error

Erreur interne du gateway. Retentez la requête. Si le problème persiste, vérifiez status.afrimap.ci et contactez le support avec le header X-Request-Id de la réponse.

502

Bad Gateway

Le service en aval (Valhalla, Pelias, Martin, TTS) n'a pas répondu correctement. C'est généralement transitoire. Pour la synthèse vocale, cela signifie que le moteur TTS est temporairement indisponible.

503

Service Unavailable

Maintenance ou surcharge. Vérifiez status.afrimap.ci. La page de statut affiche l'état de chaque service en temps réel.

Techniques de debugging

1. Utilisez le Playground

Le Playground interactif appelle l'API directement depuis votre navigateur. Pas de proxy, pas de cache — vous voyez exactement la requête et la réponse.

2. Inspectez les headers de réponse

Chaque réponse inclut des headers utiles pour le debugging :

TerminalHeaders de diagnostic

 X-Request-Id: req_01HZ... # ID unique de la requête (à fournir au support) X-Cache: HIT | MISS # Résultat du cache Redis X-Backend: valhalla | pelias # Service ayant traité la requête X-Model-Variant: xtts_v2_base # Modèle TTS utilisé (sur /navigate/voice) X-RateLimit-Remaining: 9842 # Requêtes restantes

3. Vérifiez les coordonnées

L'erreur la plus fréquente est l'inversion lat/lng. AfriMap utilise :

Pour les requêtes JSON

JSONObjet LatLng

 { "lat": 5.3197, "lng": -4.0167 }

Pour les query strings

TerminalParamètres URL

 ?lat=5.3197&lng=-4.0167 # ou format compact : ?origin=5.3197,-4.0167

GeoJSON utilise l'ordre inverse : [lng, lat] = [-4.0167, 5.3197]. C'est le standard GeoJSON, pas une erreur AfriMap. Les réponses spatiales suivent cette convention.

4. Coordonnées de test Abidjan

Utilisez ces coordonnées pour vos tests — elles sont garanties de fonctionner :

Lieu	Latitude	Longitude
Plateau (centre-ville)	5.3197	-4.0167
Cocody	5.3480	-3.9904
Yopougon	5.3364	-4.0694
Abobo	5.4194	-4.0200

API Routing → ← Authentification