Errors - Footstep

When a request fails, the API returns a consistent JSON error body with an HTTP status code. This page covers every error you might encounter, what causes it, and how to handle it.

Error shape

Every error response has the same structure:

{
  "error": "error_code",
  "message": "Human-readable description"
}

The error field is a stable, machine-readable code you can match on in your code. The message field is a human-readable explanation that may change over time, so don’t parse it programmatically.

Error codes

Client errors (4xx)

These indicate a problem with the request. Fix the issue before retrying.

HTTP status	Code	Description	Common cause
`400`	`bad_request`	Invalid request body or parameters	Malformed JSON, missing required fields, coordinates outside valid range
`401`	`unauthorized`	Missing or malformed API key	No `x-api-key` header, or key doesn’t match the `sk_live_*` format
`402`	`payment_required`	Account balance is empty	Top up at console.footstep.ai. The key is fine — only the balance is blocking the request
`403`	`forbidden`	Invalid, suspended, or revoked API key	Key was deleted, suspended by admin, or doesn’t exist
`404`	`not_found`	Endpoint does not exist	Typo in the URL path, or using an unsupported HTTP method
`408`	`request_timeout`	Request took too long to process	Very long routes, complex optimisation problems, or temporary server load
`429`	`too_many_requests`	Rate limit exceeded	Per-product per-second cap exceeded for your API key. Back off and retry — the response body’s `retryAfter` field gives the milliseconds until the next request will succeed. See per-product caps below.

Rate limits per product

Each product has its own per-second budget per API key. Hitting one cap does not affect the others — a customer using the routing API at full speed has full geocoding capacity available in parallel.

Product	Default cap	Endpoints
Geocoding	10 req/sec	`/v1/geocoding/*`, `/v1/routing/find-and-route`, `/v1/routing/search-along-route`
Routing	20 req/sec	`/v1/routing/route`, `/matrix`, `/isochrone`, `/snap`, `/locate`, `/elevation`, `/optimize`, `/compare`
AI	5 req/sec	`/v1/ai/*`
Predict	2 req/sec	`/v1/predict`
Telemetry	50 req/sec	`/v1/telemetry/*`

Note that /v1/routing/find-and-route and /v1/routing/search-along-route count against the geocoding cap, not the routing cap, because they internally perform a geocode. When you exceed a cap, the response is 429 too_many_requests with a retryAfter field giving the milliseconds until your next request will succeed.

Server errors (5xx)

These indicate a problem on our side. They are usually transient and safe to retry.

HTTP status	Code	Description	Common cause
`502`	`bad_gateway`	Upstream service unreachable	The routing engine is starting up or temporarily unreachable
`503`	`service_unavailable`	Routing engine temporarily unavailable	Maintenance or deployment in progress
`504`	`gateway_timeout`	Upstream service timed out	The routing engine took too long to respond

Handling errors in code

Check the HTTP status code first, then read the error field for specifics:

const response = await fetch("https://api.footstep.ai/v1/routing/route", {
  method: "POST",
  headers: {
    "x-api-key": process.env.FOOTSTEP_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ locations }),
});

if (!response.ok) {
  const { error, message } = await response.json();

  switch (error) {
    case "bad_request":
      // Fix the request, don't retry
      console.error("Invalid request:", message);
      break;
    case "unauthorized":
    case "forbidden":
      // Check your API key
      console.error("Auth failed:", message);
      break;
    case "too_many_requests":
      // Back off and retry
      break;
    default:
      // Server error, retry with backoff
      break;
  }
}

import os
import requests

response = requests.post(
    "https://api.footstep.ai/v1/routing/route",
    headers={"x-api-key": os.environ["FOOTSTEP_API_KEY"]},
    json={"locations": locations},
)

if not response.ok:
    data = response.json()
    error = data["error"]
    message = data["message"]

    if error == "bad_request":
        # Fix the request - don't retry
        raise ValueError(f"Invalid request: {message}")
    elif error in ("unauthorized", "forbidden"):
        # Check your API key
        raise PermissionError(f"Auth failed: {message}")
    elif error == "too_many_requests":
        # Back off and retry
        pass
    else:
        # Server error - retry with backoff
        pass

Retry strategy

Some errors are transient and safe to retry. Use exponential backoff with jitter to avoid thundering herd problems, where all your retries hit the server at the same time:

async function fetchWithRetry(url, options, maxRetries = 3) {
  const retryable = new Set([408, 429, 502, 503, 504]);

  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    const response = await fetch(url, options);

    if (response.ok || !retryable.has(response.status)) {
      return response;
    }

    if (attempt < maxRetries) {
      // Exponential backoff: 1s, 2s, 4s... capped at 30s
      const delay = Math.min(1000 * 2 ** attempt, 30000);
      // Add random jitter (50-100% of delay) to spread out retries
      const jitter = delay * (0.5 + Math.random() * 0.5);
      await new Promise((resolve) => setTimeout(resolve, jitter));
    }
  }
}

Safe to retry	Do not retry
`408` `429` `502` `503` `504`	`400` `401` `402` `403` `404`

Common mistakes

Getting 401 but I'm sending a key

Make sure you’re using the x-api-key header (not Authorization or api-key), and that your key starts with sk_live_. Keys passed as query parameters or in the request body are not recognised.

Getting 400 with valid-looking coordinates

Check that latitude is between -90 and 90, and longitude is between -180 and 180. A common mistake is swapping lat/lon. If your latitude is something like 51.5 but your longitude is 151.2, the coordinates may point to an area with no road network data.

​Error shape

​Error codes

​Client errors (4xx)

​Rate limits per product

​Server errors (5xx)

​Handling errors in code

​Retry strategy

​Common mistakes