Erros

Como são os erros

Os erros respondem com um código HTTP e o mesmo envelope JSON, quer sejam erros de chave, de quota ou próprios de uma API. reason é estável: o seu programa pode confiar nele. message destina-se às pessoas: diz exatamente o que aconteceu e como resolver, e pode ser reformulado. details contém o ErrorInfo da Google (o motivo e, em metadata, os factos que o explicam e a ligação docs) e uma ligação Help para a entrada do motivo nesta página.

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

Cada resposta tem também um cabeçalho X-Request-Id: junte-o a qualquer pergunta enviada à assistência. Confie no código e no motivo, nunca nas palavras da mensagem.

Códigos HTTP

Erros de chave, de plataforma, de quota e de faturação

Quando uma chamada é recusada, a resposta diz exatamente porquê e como resolver. O N-Ways verifica, por esta ordem: a plataforma (ligada), a chave (fornecida, emitida e não revogada), a sua organização e o seu projeto (nem fechados nem suspensos), o estado da chave (não em pausa), as suas restrições (a API, depois o site, a aplicação ou o endereço IP), os seus limites e quotas, e por fim o crédito. O primeiro ponto que falha dá a resposta.

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

As mensagens estão em inglês. metadata contém sempre docs, e os factos de que o seu código pode precisar: o que foi visto (seen) e o que é permitido (allowed) para as restrições e as API, o limite atingido (cap) com o seu limit e a sua reposição (resetsAt) para os 429, until e suspendReason para as suspensões, why e revokedAt para as chaves revogadas, keyValid quando a plataforma está desligada. Cada recusa traz também X-Request-Id.

Desde 16 de outubro de 2026, PARTNER_SUSPENDED passou a ORGANISATION_SUSPENDED, uma organização desativada pelo N-Ways responde ORGANISATION_SUSPENDED e já não PROJECT_SUSPENDED, e as chaves eliminadas ou regeneradas respondem API_KEY_REVOKED e já não API_KEY_INVALID.

As recusas e os pedidos preliminares (preflight) trazem sempre os cabeçalhos CORS da página que faz a chamada, tanto em /maps/v1 como nos endereços antigos (/v1, /tiles, /fonts), para que o seu código (e a nota do SDK Maps no mapa) possa ler o motivo, mesmo quando a plataforma está desligada.

Os motivos de cada API

Cada operação da referência da API lista os seus próprios motivos. Os que vai encontrar com mais frequência:

Repetir bem

• Repita apenas os 429 e os 5xx, com esperas crescentes e um pouco de aleatoriedade, para que muitos clientes não repitam todos ao mesmo tempo.
• Nunca reenvie tal como está um pedido que recebeu um 4xx que não seja 429: vai falhar da mesma forma.
• Defina um tempo limite: 10 segundos para a geocodificação e os lugares, 20 para os percursos.
• Guarde em cache o que tem direito a guardar (veja o que pode guardar), para que uma falha curta não pare os seus estafetas.