Codes d'erreur

Référence rapide

Statut HTTP	Code d'erreur	Quand il survient
400	`MISSING_PARAMETER`	Un paramètre de requête requis n'est pas fourni
400	`INVALID_PARAMETER`	Une valeur de paramètre est hors plage ou du mauvais type
401	`INVALID_API_KEY`	La clé API est manquante, invalide ou révoquée
403	`PLAN_UPGRADE_REQUIRED`	La feature n'est pas incluse dans votre plan (ne consomme jamais de crédit)
404	`NOT_FOUND`	La ressource n'existe pas ou n'appartient pas à votre compte
409	`JOB_NOT_READY`	Les résultats d'un job batch sont demandés avant sa complétion
429	`RATE_LIMIT_EXCEEDED`	Trop de requêtes par seconde pour votre plan
429	`QUOTA_EXCEEDED`	Quota de crédits épuisé pour la fenêtre en cours (journalière sur Free, mensuelle sur les plans payants)
500	`INTERNAL_ERROR`	Défaillance inattendue côté serveur (crédits remboursés automatiquement)
502	`INTERNAL_ERROR`	Un moteur amont (géocodage/routage) a échoué
503	`SERVICE_UNAVAILABLE`	La feature n'est pas encore provisionnée sur ce déploiement (réessayable)

Format des erreurs

Toutes les erreurs suivent une structure JSON cohérente :

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description of the error",
    "field": "parameter_name",
    "retry_after": 1,
    "quota_reset": 1753056000,
    "upgrade_url": "https://geocodeme.net/dashboard/billing"
  }
}

Champ	Type	Présent	Description
`code`	string	Toujours	Code d'erreur lisible par machine
`message`	string	Toujours	Description de l'erreur lisible par un humain
`field`	string	`MISSING_PARAMETER`, `INVALID_PARAMETER` uniquement	Le paramètre à l'origine de l'erreur
`retry_after`	integer	`RATE_LIMIT_EXCEEDED` uniquement	Secondes à attendre avant de réessayer
`quota_reset`	integer	`QUOTA_EXCEEDED` uniquement	Timestamp Unix de réinitialisation de la fenêtre de quota
`upgrade_url`	string	`PLAN_UPGRADE_REQUIRED`, `QUOTA_EXCEEDED`	Où monter de plan

Détail des erreurs

MISSING_PARAMETER

Statut HTTP : 400

Renvoyée quand un paramètre de requête requis n'est pas fourni dans la requête.

Correctif : Ajoutez le paramètre manquant à votre requête. Consultez la documentation de l'endpoint pour connaître les paramètres requis.

{
  "error": {
    "code": "MISSING_PARAMETER",
    "message": "Required parameter 'q' is missing",
    "field": "q"
  }
}

INVALID_PARAMETER

Statut HTTP : 400

Renvoyée quand une valeur de paramètre est en dehors de la plage autorisée ou d'un type incorrect.

Correctif : Vérifiez les contraintes du paramètre dans la documentation de l'endpoint et corrigez la valeur.

{
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "Parameter 'lat' must be between -90 and 90",
    "field": "lat"
  }
}

INVALID_API_KEY

Statut HTTP : 401

Renvoyée quand le header X-Api-Key ou le paramètre de requête api_key est manquant, mal formé, ou fait référence à une clé révoquée.

Correctif : Vérifiez votre clé API dans le Tableau de bord. Régénérez la clé si elle a été révoquée.

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "API key missing or invalid"
  }
}

PLAN_UPGRADE_REQUIRED

Statut HTTP : 403

Renvoyée quand votre plan n'inclut pas la feature demandée : un profil de véhicule (bike/foot dès Startup, truck/moto dès Growth), une isochrone ou une matrice au-delà du plafond de votre plan, l'altimétrie, les tuiles vectorielles ou le batch. Un 403 ne consomme jamais de crédit.

Correctif : Montez de plan via upgrade_url, ou adaptez la requête aux capacités de votre plan (voir Crédits & quotas).

{
  "error": {
    "code": "PLAN_UPGRADE_REQUIRED",
    "message": "Profile 'truck' requires the growth plan or higher",
    "upgrade_url": "https://geocodeme.net/dashboard/billing"
  }
}

RATE_LIMIT_EXCEEDED

Statut HTTP : 429

Renvoyée quand vous dépassez la limite de débit par seconde de votre plan. Le champ retry_after indique combien de secondes attendre.

Correctif : Implémentez un backoff exponentiel. Consultez Limitation de débit pour un exemple de code.

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Try again in 1 second",
    "retry_after": 1
  }
}

QUOTA_EXCEEDED

Statut HTTP : 429

Renvoyée quand votre quota de crédits est épuisé pour la fenêtre en cours : la journée (reset à minuit UTC) sur Free, le mois calendaire sur les plans payants. Le champ quota_reset est le timestamp Unix de réinitialisation.

Correctif : Passez à un plan supérieur pour une enveloppe plus grande, ou attendez la réinitialisation.

{
  "error": {
    "code": "QUOTA_EXCEEDED",
    "message": "Quota exceeded. Upgrade your plan to continue.",
    "quota_reset": 1753056000,
    "upgrade_url": "https://geocodeme.net/dashboard/billing"
  }
}

INTERNAL_ERROR

Statut HTTP : 500

Renvoyée quand une erreur inattendue survient côté serveur.

Correctif : Réessayez la requête une fois après un court délai. Si l'erreur persiste, contactez le support. Les crédits débités pour une requête finissant en 5xx sont remboursés automatiquement.

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An unexpected error occurred. Please try again later"
  }
}

JOB_NOT_READY

Statut HTTP : 409

Renvoyée par GET /v1/batch/{job_id}/result tant que le job est queued ou running (ou après un failed).

Correctif : Interrogez GET /v1/batch/{job_id} jusqu'à ce que status vaille completed, puis téléchargez les résultats.

{
  "error": {
    "code": "JOB_NOT_READY",
    "message": "Job is 'running': results are only available once completed"
  }
}

SERVICE_UNAVAILABLE

Statut HTTP : 503

Renvoyée quand une feature existe mais n'est pas encore provisionnée sur ce déploiement (ex. autocomplete pendant le déploiement de ses instances).

Correctif : Réessayez plus tard ; condition temporaire côté déploiement.

{
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "Autocomplete is not provisioned on this deployment yet"
  }
}

Référence rapide​

Format des erreurs​

Détail des erreurs​

MISSING_PARAMETER​

INVALID_PARAMETER​

INVALID_API_KEY​

PLAN_UPGRADE_REQUIRED​

RATE_LIMIT_EXCEEDED​

QUOTA_EXCEEDED​

INTERNAL_ERROR​

JOB_NOT_READY​

SERVICE_UNAVAILABLE​