Errors

The Data API returns three kinds of error: validation errors (422), errors with a Data API error code, and standard HTTP errors. This page lists each one and shows how to handle them.

The error envelope

An error with a Data API error code has a JSON body with one top-level error key. Branch on code. Log message. details carries values you can act on, such as the invalid input. This request has no radius_m and no k, so it returns 400 with the code range_required.

curl -H "Authorization: Bearer $POI_API_KEY" \
  "$POI_BASE/v1/pois/near?country=GB&lat=51.5074&lng=-0.1278&category=cafe&limit=5"

{
  "error": {
    "code": "range_required",
    "message": "one of radius_m or k is required",
    "details": {}
  }
}

POST /v1/cells/rank and the 429 response use a flat form. The details sit beside code and message, and schema_version names the contract version. This is the response to a ranking request with 10,001 cells.

{
  "error": {
    "code": "max_cells_exceeded",
    "message": "Request exceeds max 10000 cells (got 10001).",
    "schema_version": "2.0.0",
    "limit": 10000,
    "actual": 10001
  }
}

Read error.code and error.message and both forms work.

Error codes

Every code below arrives in the envelope. The third column is the HTTP status.

HTTP statuses

An error without a Data API code has a detail field instead of error. detail is a string, or a list for 422.

With Accept: application/x-ndjson, POST /v1/search/reachable streams its reply in two lines and the status goes out with the first. An error in the second step arrives as a final line {"error": {"code": "...", "message": "..."}} on a 200. The code is the one the plain reply would have returned, such as a 503 code above, or internal_error for anything else. See Stream the reply.

A validation error

422 is the most common error while you build a request. This POST /v1/h3/pois body sets no geography, so the API rejects it.

curl -X POST -H "Authorization: Bearer $POI_API_KEY" -H "Content-Type: application/json" \
  -d '{}' "$POI_BASE/v1/h3/pois?country=GB"

{
  "detail": [
    {
      "type": "value_error",
      "loc": ["body"],
      "msg": "Value error, exactly one of cells / bbox / (center_lat+center_lng+radius_m) must be set",
      "input": {},
      "ctx": {
        "error": {}
      }
    }
  ]
}

Each entry in detail describes one failed field.

• type is the kind of failure, such as missing, too_short or value_error.
• loc is the path to the field, such as ["body", "cells"] or ["query", "country"].
• msg is a sentence for your logs.
• input is the value we received.
• ctx is extra context for some types.

Every problem with the request is in the one response. You do not need to fix one and resend to find the next.

What to show your users

Show error.message for an error with a code. Treat a 422 as a bug in your request: log it and do not show it. On 401, ask the user to sign in again. On 429, wait for the number of seconds in Retry-After, then retry. This handler covers every error the Data API returns.

async function handle(response: Response) {
  if (response.ok) return response.json()

  const body = await response.json().catch(() => null)

  if (body?.error?.code) {
    // Data API error code: show body.error.message, branch on body.error.code if needed.
    throw new ApiError(body.error.code, body.error.message)
  }

  if (Array.isArray(body?.detail)) {
    // 422 validation error: a bug in the request, so log it.
    throw new ValidationError(body.detail)
  }

  if (response.status === 401) throw new AuthError('Please sign in again')
  if (response.status === 429) throw new RateLimitError(response.headers.get('Retry-After'))
  throw new UpstreamError(response.status, body?.detail ?? response.statusText)
}

Get help

Contact us at traveltime.com/contact-us.