Copy page

Getting started

Error responses | Rijwind docs

Error responses

Every non-2xx response from api.rijwind.com returns the same JSON envelope:

Code
{
  "error": "machine_readable_code",
  "message": "Human-readable explanation."
}

You can rely on:

• error is a stable identifier — match against it in code.
• message is for humans — show it to the developer, but don't switch on it in code (we may rewrite it for clarity).
• The HTTP status code is set correctly. Treat any 4xx/5xx as a failure even if you can't recognise the error value yet.

Codes you'll see

400 Bad Request

The request shape is malformed or invalid. Fix the request and retry.

error	Cause
bad_request	The request body or query is invalid. Branch on the message field for the sub-reason — common ones are listed below.

The error code is always bad_request for 4xx-shape problems; the human-readable message distinguishes between sub-cases. Examples:

• "bad request: costing 'truck' is not supported; allowed: auto, bicycle, pedestrian" — the costing field is not one of auto, bicycle, or pedestrian.
• "bad request: matrix request too large: 60 × 60 = 3600 pairs exceeds the 2500 cap" — len(sources) × len(targets) > 2500. Split into multiple smaller matrix calls.
• "bad request: isochrone request too large: 2 × 3 = 6 pairs exceeds the 4 cap" — len(locations) × len(contours) > 4. Run separate calls per origin or contour.
• "bad request: invalid JSON" — the body could not be parsed, or a required field is missing.

Match on error === "bad_request" in code; treat message as human-readable only.

400s never charge quota.

401 Unauthorized

The Bearer key is missing or unknown.

error	Cause
missing_key	No Authorization header (and no ?key= fallback) on the request.
invalid_key	The key doesn't exist in our index. Likely a typo.

Revoked keys return 403 key_revoked — see the 403 section below.

401s never charge quota.

403 Forbidden

The key is valid but the request is not authorised — either it came from a blocked origin or the endpoint is outside the key's scope.

error	Cause
origin_not_allowed	The request's Origin/Referer didn't match the project's allowed-origins whitelist.
origin_required	The project requires an Origin/Referer and neither was sent.
key_revoked	The key has been revoked from the dashboard.
scope_denied	The endpoint is outside the key's scope list. Reissue with the missing scope, or use a full-access key.

403s never charge quota.

If a server-side script trips origin_not_allowed, either drop the Origin header (most HTTP clients do that by default) or clear the allowed-origins list on that key.

429 Too Many Requests

The monthly quota is exhausted (hard cap) or an upstream component is shedding load.

error	Cause
quota_exhausted	You hit monthly_request_limit and the plan is on cap_mode=hard. Resets at the end of your current 30-day cycle — anchored on your billing anniversary (paid plans) or email-verification date (free plan). Your dashboard shows the exact next-reset timestamp.

502 Bad Gateway

A backend service timed out or is restarting. This is transient — retry with exponential backoff. We log every 502 on our side and don't need you to file a ticket unless they persist for more than a few minutes.

503 Service Unavailable

Brief planned-maintenance windows for data refreshes — see status updates on rijwind.com for timing. Same retry advice as 502.

Retrying safely

• Read endpoints (GET /v1/tiles-token, /v1/geocode/*) are idempotent — retry freely.
• Routing endpoints (POST /v1/route, /v1/matrix, /v1/isochrone) are also idempotent in the absence of side effects; re-sending the same request always produces the same answer. Retry freely on 502/503.
• For 429: don't retry tighter than the start of the next quota period. The dashboard shows your reset timestamp.