Erreurs

À quoi ressemblent les erreurs

Les erreurs répondent avec un code HTTP et une même enveloppe JSON, qu’il s’agisse d’erreurs de clé, de quota ou propres à une API. reason est stable : votre programme peut s’y fier. message s’adresse aux personnes : il dit exactement ce qui s’est passé et comment y remédier, et peut être reformulé. details contient l’ErrorInfo de Google (le motif et, dans metadata, les faits qui l’expliquent et le lien docs) et un lien Help vers l’entrée du motif sur cette page.

{
  "error": {
    "code": 400,
    "status": "INVALID_ARGUMENT",
    "reason": "TOO_MANY_INTERMEDIATES",
    "message": "A route has up to 25 intermediates.",
    "details": [
      { "@type": "type.googleapis.com/google.rpc.ErrorInfo", "reason": "TOO_MANY_INTERMEDIATES", "domain": "nways.ng",
        "metadata": { "docs": "https://nways.ng/developers/errors#api-reasons" } },
      { "@type": "type.googleapis.com/google.rpc.Help",
        "links": [{ "description": "TOO_MANY_INTERMEDIATES: what it means and how to fix it", "url": "https://nways.ng/developers/errors#api-reasons" }] }
    ]
  }
}

Chaque réponse a aussi un en-tête X-Request-Id : joignez-le à toute question adressée à l’assistance. Fiez-vous au code et au motif, jamais aux mots du message.

Codes HTTP

Erreurs de clé, de plateforme, de quota et de facturation

Quand un appel est refusé, la réponse dit exactement pourquoi et comment y remédier. N-Ways vérifie, dans cet ordre : la plateforme (allumée), la clé (fournie, émise et non révoquée), son organisation et son projet (ni fermés ni suspendus), l’état de la clé (pas en pause), ses restrictions (l’API, puis le site web, l’application ou l’adresse IP), ses limites et quotas, puis le crédit. Le premier point qui échoue donne la réponse.

{
  "error": {
    "code": 403,
    "status": "PERMISSION_DENIED",
    "reason": "API_KEY_PAUSED",
    "message": "The API key nw_8fK2q… (“Checkout”) is paused, so its calls are refused. Resume it in the console (https://map.nways.ng/console, Keys → the key → Resume); it works again within 30 seconds.",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "API_KEY_PAUSED",
        "domain": "nways.ng",
        "metadata": { "docs": "https://nways.ng/developers/errors#api-key-paused", "keyPrefix": "nw_8fK2q" }
      },
      {
        "@type": "type.googleapis.com/google.rpc.Help",
        "links": [{ "description": "API_KEY_PAUSED: what it means and how to fix it", "url": "https://nways.ng/developers/errors#api-key-paused" }]
      }
    ]
  }
}

Les messages sont en anglais. metadata contient toujours docs, et les faits dont votre code peut avoir besoin : ce qui a été vu (seen) et ce qui est autorisé (allowed) pour les restrictions et les API, le plafond atteint (cap) avec sa limit et sa remise à zéro (resetsAt) pour les 429, until et suspendReason pour les suspensions, why et revokedAt pour les clés révoquées, keyValid quand la plateforme est coupée. Chaque refus porte aussi X-Request-Id.

Depuis le 16 octobre 2026, PARTNER_SUSPENDED devient ORGANISATION_SUSPENDED, une organisation désactivée par N-Ways répond ORGANISATION_SUSPENDED et non plus PROJECT_SUSPENDED, et les clés supprimées ou régénérées répondent API_KEY_REVOKED et non plus API_KEY_INVALID.

Les refus et les requêtes préliminaires (preflight) portent toujours les en-têtes CORS de la page appelante, sur /maps/v1 comme sur les anciennes adresses (/v1, /tiles, /fonts), pour que votre code (et la note du SDK Maps sur la carte) puisse lire le motif, même quand la plateforme est coupée.

Les motifs de chaque API

Chaque opération de la référence de l’API liste ses propres motifs. Ceux que vous rencontrerez le plus souvent :

Bien réessayer

• Ne réessayez que les 429 et les 5xx, avec des attentes croissantes et un peu de hasard, pour que de nombreux clients ne réessaient pas tous en même temps.
• Ne renvoyez jamais telle quelle une requête qui a reçu un 4xx autre que 429 : elle échouera de la même façon.
• Fixez un délai d’attente : 10 secondes pour le géocodage et les lieux, 20 pour les itinéraires.
• Mettez en cache ce que vous avez le droit de garder (voyez ce que vous pouvez conserver), pour qu’une courte panne n’arrête pas vos livreurs.