Errors

Every error you'll see falls into one of three buckets: request validation errors (422), structured domain errors, or standard HTTP statuses (401, 403, 404, 5xx). This page enumerates each so you can write a single error handler that covers everything the API actually emits.

The envelope

Domain errors are wrapped in a JSON envelope under a top-level error key:

{
  "error": {
    "code": "anchor_required",
    "message": "one of (lat+lng) or poi_id is required",
    "details": {}
  }
}

The ranking routes use a slightly different shape: details is flattened onto the envelope alongside code and message, and a schema_version field is included so clients can key error handling to the contract version.

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

Domain error codes

Application-level codes raised by our routers. Every code below ships inside the envelope shown above; the HTTP status is the one in the third column.

Standard HTTP statuses

Anything not in the table above is one of these. They come back with the standard error shape — usually a { "detail": "..." } string body, or { "detail": [...] } for 422.

A validation-error example

The most common error path is 422 — the server rejected something in your request body or query parameters. A real response:

{
  "detail": [
    {
      "type": "too_short",
      "loc": ["body", "cells"],
      "msg": "Dictionary should have at least 1 item after validation, not 0",
      "input": {},
      "ctx": { "field_type": "Dictionary", "min_length": 1, "actual_length": 0 }
    }
  ]
}

Every entry in detail describes one failed field:

• type — the validation error type (missing, too_short, extra_forbidden, string_pattern_mismatch, etc.).
• loc — the path to the offending field (["body", "cells"], ["query", "country"]).
• msg — a human-readable summary.
• input — the actual value we received.
• ctx — optional, type-specific context.

Treat the array as exhaustive: every problem with the request is reported in one response, not one-at-a-time.

What to surface to your end user

A reasonable client-side error handler looks something like this:

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

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

  if (body?.error?.code) {
    // Structured domain error — 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 — usually a programmer error, log it loudly.
    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)
}

The branches map 1-to-1 onto the buckets at the top of this page: structured envelope, validation array, standard status. If you cover those three you've covered everything the API emits.