Errors

How errors look

Errors answer with an HTTP status and one JSON envelope, for key, quota and product errors alike. reason is stable: your program can act on it. message is for people: it says exactly what happened and how to fix it, and may be reworded. details holds Google’s ErrorInfo (the reason, and in metadata the facts behind it and the docs link) and a Help link to the reason’s entry on this 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" }] }
    ]
  }
}

Every answer also has an X-Request-Id header: send it with any question to support. Act on the status and the reason, never on the message’s words.

HTTP statuses

Key, platform, quota and billing errors

When a call is refused, the answer says exactly why and how to fix it. N-Ways checks, in this order: the platform (switched on), the key (given, issued and not revoked), its organisation and project (not closed or suspended), the key’s own state (not paused), its restrictions (the API, then the website, app or IP address), its limits and quotas, then credit. The first that fails is the answer.

{
  "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" }]
      }
    ]
  }
}

metadata always has docs, and the facts your code may need: what was seen and what is allowed (restrictions and APIs), which cap was hit with its limit and resetsAt (429s), until and suspendReason (suspensions), why and revokedAt (revoked keys), keyValid (the platform switched off). Every refusal also carries X-Request-Id.

Since 16 October 2026, PARTNER_SUSPENDED is ORGANISATION_SUSPENDED, an organisation disabled by N-Ways is ORGANISATION_SUSPENDED rather than PROJECT_SUSPENDED, and deleted or regenerated keys are API_KEY_REVOKED rather than API_KEY_INVALID.

Refusals and preflights always carry CORS headers for the calling page, on /maps/v1 and on the earlier addresses (/v1, /tiles, /fonts) alike, so your code (and the Maps SDK’s note over the map) can read the reason, even while the platform is switched off.

Each API’s reasons

Each operation in the API reference lists its own reasons. The ones you’ll meet most:

Retrying well

• Retry 429 and 5xx only, with growing waits and a little randomness, so many clients don’t retry at once.
• Never retry a 4xx other than 429 unchanged: it will fail the same way.
• Set a timeout: 10 seconds for geocoding and places, 20 for routes.
• Cache what you may (see what you may store), so a short outage doesn’t stop your riders.