Errors and limits

Tareky Console

The error shape

Every /v1 error has the same shape. Branch on code, not on the message:

{
  "error": {
    "code": "quota_exceeded",
    "message": "Monthly quota exhausted for this app",
    "status": 429,
    "docsUrl": "https://docs.tareky.com/errors/#quota_exceeded"
  },
  "requestId": "…"
}

Quote requestId when you contact us: it finds your request in our logs.

Limits and units

• Each call spends units from your plan’s monthly quota. Most cost 1. Travel-time matrices, stop optimisation, static maps and transit plans cost 3, and map matching and places along a route cost 2.
• Only successful (2xx) calls are billed. Anything else gives its units back.
• A map is billed once, when its style loads (GET /v1/styles/{theme}). Its tiles are free.
• Months start on Baghdad time.

Every response carries:

Header	Meaning
X-RateLimit-Limit	Requests a minute allowed for the key
X-RateLimit-Remaining	What’s left of them this minute
X-RateLimit-Reset	Seconds until the next minute
X-Quota-Limit	Units a month on your plan (metered plans)
X-Quota-Remaining	What’s left of them

Over a limit you get 429 with Retry-After in seconds.

Codes

missing_key

No key on the request (401). Send it as Authorization: Bearer …, or a public key as ?access_token=.

invalid_key

The key is wrong, revoked or expired (401).

forbidden

Not allowed (403): for example a secret key in a URL, or a suspended app.

account_suspended

The account that owns the key is deleted or suspended (403). The keys work again if the account is restored.

origin_not_allowed

The public key is restricted to origins this request doesn’t come from (403). Add your site’s origin in the console.

app_not_allowed

The public key is restricted to apps this request doesn’t come from (403): it carries no origin, and its X-Ios-Bundle-Identifier or X-Android-Package / X-Android-Cert match none of the key’s apps.

ip_not_allowed

The secret key is restricted to addresses this request doesn’t come from (403). Add your server’s address, or its range, to the key in the console.

scope_not_allowed

The API isn’t one the key is allowed (403).

traffic_not_enabled

The traffic API is not enabled for partners on this deployment yet (403). Ask us to switch it on.

rate_limited

Too many requests a second or a minute (429). Wait for Retry-After.

quota_exceeded

The month’s units are used up (429). They come back when the month starts on Baghdad time, or ask for a bigger plan.

invalid_request

Invalid input (400 or 422). The specifics are in details.

not_found

Not found (404).

conflict

Conflicts with the current state (409).

payload_too_large

The request is larger than allowed (413).

no_route

No route between the given points (400).

no_segment

A point is too far from any road (400).

no_match

The trace couldn’t be matched to roads (400).

no_trips

No trip could be ordered between the stops (400).

too_big

Larger than the service allows, such as too many coordinates (400).

service_unavailable

Temporarily unavailable (503). Try again later.

internal_error

An internal error (500). Quote requestId when you contact us.

Console codes

The console, and the tileset build API, answer some failures with a more specific code than the list above. Over /v1 (the build API) the same failure arrives as the general code of its status, such as forbidden for a plan limit or invalid_request for a bad input, and the message says why. The console’s own requests add the code below to the body. Those answers carry no docsUrl: the console shows them in words, and this list is for finding out more.

role_forbidden

Your role in the organisation can’t do that (403). The message names the role and the action, such as styles.publish. Ask an owner or admin: see who can do what.

style_limit

Your plan’s number of styles is used up (403). Delete a style you don’t use, or ask for a bigger plan.

style_too_large

The style is larger than your plan allows (422). The message gives both sizes. Remove layers or icons, or ask for a bigger plan.

style_invalid

The style breaks a rule (422). problems lists each one, and issues says where it is (layers[3].paint.fill-color). The most common are an address that is not a tareky:// name, a font you haven’t uploaded, a tileset that isn’t yours or isn’t built, and a layer or size over your plan’s limit. See custom styles.

style_unrenderable

Our renderer couldn’t draw the style, so publishing was refused (422). problems says why. Fix it and publish again.

stale_revision

The draft changed since you opened it, in another tab or by a teammate (409). The body carries the current revision. Reload the style; nothing was overwritten. See saving and conflicts.

icon_invalid

The icon is refused (422). problems says why: an SVG that holds scripts, images or links, an SVG or PNG over 32 KB, a PNG over 256×256 pixels, or a file that is not an image.

icon_limit

The style holds as many icons as your plan allows (403).

icon_not_found

No icon of the library has that id (404).

share_link_limit

The style already has 10 live share links (403). Revoke one first.

comment_limit

The style has 500 comments (403). Delete some.

licence_not_attested

A font was uploaded without confirming you may use it in maps and share its glyphs (422). Tick the statement.

stack_name_invalid

The font’s name can’t be used in a style (422). Use letters, digits, spaces, ., _ and -, up to 64, starting with a letter or digit.

stack_name_reserved

The name is one of the platform’s fonts (422). Choose another.

stack_name_taken

You already have a font with that name (409).

font_invalid

The file is not a font we accept (422). reason says why: not a TrueType, OpenType or WOFF file, WOFF2, or a font collection.

font_limit

Your plan’s number of fonts is used up (403). Failed fonts don’t count.

font_in_use

A published style uses the font (409). styles names them. Publish a version without it first.

font_too_large

The font file is over 10 MB (413).

upload_missing

The file was never uploaded, or was removed (422). Upload it again, then register it.

upload_too_large

The file is larger than your plan allows (413). maxMb is the limit.

tileset_limit

Your plan’s number of tilesets is used up (403).

tileset_kind_changed

A tileset keeps the kind of its first build (409): vector, raster or raster-dem. Use another name for a different kind.

format_kind_mismatch

A GeoTIFF was built as a vector tileset, or something else as imagery or elevation (422). Build a GeoTIFF as raster or raster-dem, and everything else as vector.

recipe_layers_vector_only

layers in a recipe is for vector tilesets (422). Imagery and elevation are one image pyramid.

dem_format_png_only

An elevation tileset is PNG (422): a lossy format would change the heights.

source_layer_missing

The recipe names a layer the upload does not have (422). layers lists the ones it has.

layer_not_found

A join names a layer the tileset does not have (422). layers lists them.

layer_required

The tileset has several layers, so a join must say which (422). Send layer.

no_source

There is nothing kept to rebuild or join from (409). Upload a file first.

join_vector_only

Only a vector tileset has features to join to (409).

job_finished

That build had already finished, so it can’t be cancelled (409).

tileset_in_use

A published style draws the tileset (409), so it can’t be deleted. style names it.

external_id_taken

Another geofence of the app has that external id (409). In the console, creating a geofence with a taken id is refused rather than replacing the existing one, as the /v1 API does; renaming one onto a taken id is refused everywhere.

app_required

The organisation has several apps (or none), so the request must say which (422). Send appId, or create an app first.

export_failed

The activity export could not finish (500). Try again.