Every error body is {"code": "...", "message": "..."}, plus details for the codes that list it. Branch on code. The wording of message can change. See Handle errors and retries.
Fix the request
Don't retry these unchanged.
| Status |
code |
Meaning |
What to do |
| 400 |
invalid_request |
Fails the schema, or has unknown fields or parameters |
Fix the request. |
| 400 |
unsupported_profile |
Profile not offered by this deployment |
Read routing.profiles from /v2/info. |
| 400 |
too_many_points |
More than 10 route points |
Split the trip. |
| 400 |
too_many_cells |
Matrix over 25 cells |
Split the matrix. |
| 401 |
unauthorized |
Missing or invalid API key |
Send a valid X-API-Key. |
| 403 |
forbidden |
Not allowed, including a wrong HTTP method |
Use the documented method. |
| 403 |
trial_unavailable |
Keyless trial call without a valid trial session |
Send an API key. |
| 403 |
trial_exhausted |
The 5 keyless trial runs for today are used up |
Use a key, or wait for the next Philippine day. |
| 404 |
not_found |
Unknown /v2/... path |
Check the endpoint name. |
| 413 |
payload_too_large |
Body over 32 KB |
Send less. |
| 415 |
unsupported_media_type |
POST body not declared as JSON |
Send Content-Type: application/json. |
Change the points
| Status |
code |
Meaning |
What to do |
| 422 |
point_not_snapped |
A point has no road within 1 km (details.point_index) |
Move the point to within 1 km of a road. |
| 422 |
out_of_coverage |
A point is outside coverage.bbox (details.point_index) |
Check the point and its [lng, lat] order. |
| 422 |
no_route |
No path between the points, or an engine limit was hit |
Tell the user, or try nearer points. |
| 422 |
reference_not_found |
near_text found nothing |
Rephrase it, or use near. |
Retry with backoff
| Status |
code |
Meaning |
What to do |
| 429 |
rate_limited |
Over the rate limit |
Wait for Retry-After, then retry. |
| 500 |
internal_error |
An unrecognised engine reply, or a bug |
Retry once, then report it. |
| 503 |
engine_unavailable |
An engine is down |
Retry with backoff. |
| 503 |
unavailable |
The API service is unreachable |
Retry with backoff. |
| 504 |
engine_timeout |
An engine did not answer in time |
Retry with backoff, then give up. |
Don't retry
| Status |
code |
Meaning |
What to do |
| 429 |
data_cap_exceeded |
Your monthly data cap is reached |
Email contact@sieitz.com to raise it. Requests work again when the month ends (UTC). |
| 501 |
capability_unavailable |
This deployment doesn't offer the feature (details.capability) |
Read capabilities from /v2/info. |
