Errors

Every non-2xx response from the API uses a consistent JSON envelope. Your integration can branch on the type field rather than parsing free-form title/detail strings.

Envelope shape

{
  "type":     "result:no-model-for-route",
  "status":   422,
  "title":    "No assigned model covers this trip",
  "detail":   null,
  "instance": "trace-id:81fbbbd2c4fd213dad135b1d587ab6be"
}

type — stable identifier, prefixed result: (business-logic outcome) or rejection: (pre-routing rejection like bad body or missing auth). Branch on this.
status — HTTP status. Matches the response code.
title — short human-readable summary.
detail — longer human-readable explanation, or null.
instance — request-specific identifier. When non-null, prefixed trace-id: and the suffix is the W3C trace ID you'll find in your logs when correlated with our side. null if the request didn't carry a usable trace context.

Wire tags

The full set you might see. Tags not listed here are 5xx infrastructure errors — retry with backoff.

Tag	Status	Meaning
`rejection:authentication-failed`	401	Bearer-auth failure on any `/v1/*` call: JWT missing, expired, revoked, or signature invalid.
`result:invalid-credentials`	401	`/v1/auth/token` rejected the supplied `X-API-KEY` / `X-API-SECRET`.
`result:unauthorized`	401	`/v1/auth/token` called without both `X-API-KEY` and `X-API-SECRET` headers.
`result:invalid-revoke-request`	400	`/v1/auth/revoke` body must carry exactly one of `jti` or `all: true` — not both, not neither.
`rejection:static-validation-failed`	400	Request body failed validation (missing required field, type mismatch).
`rejection:route-not-found`	404	HTTP path doesn't match any endpoint.
`result:account-blocked`	403	Account is not in `Active` status (either `Blocked` or `Pending`). Contact us.
`result:customer-not-found`	404	The customer the JWT refers to no longer exists.
`result:no-model-for-route`	422	Account not assigned to a model that covers this trip's geo.
`result:model-not-allowed-for-customer`	403	The model field in your request isn't assigned to your account.
`result:model-unavailable`	503	The model is currently down. Retry shortly.
`result:model-mode-mismatch`	422	The model doesn't serve this trip's mode (e.g. requested scheduled, model only realtime).
`result:model-geo-mismatch`	422	The model doesn't cover one of the endpoints.
`result:route-metadata-incomplete`	400	You supplied one of `distanceKm`/`durationMinutes` but not the other.
`result:route-provider-unavailable`	502	You omitted `distanceKm`/`durationMinutes` and the gateway's internal route-resolution path was temporarily unreachable. Retry, or supply both values directly.
`result:inference-unavailable`	502	The pricing pipeline temporarily couldn't price this request. Safe to retry.
`result:strategy-failed`	500	An internal pricing computation produced an invalid result. Report to us with the `instance` trace.

Retry policy

Safe to retry with exponential backoff: any 5xx response (in particular result:inference-unavailable and result:route-provider-unavailable). Do not retry 4xx — they indicate a request shape your integration needs to fix.

Always log the instance trace id; if you need help, sharing it with us lets us correlate to our server-side trace in seconds.