Errors & limits

What fails, when it clears, how much you can send

The error codes, the rolling file window, the size ceilings and a bounded retry policy. Every number on this page is read from the platform's own configuration, not from a rule of thumb.

Error responses

Each failure carries a stable code. Match on the code, never on the message text: messages are localised and may be reworded, codes are the contract.

A failure uses the same envelope as a success, with ok false and the code identifying what went wrong.

{
  "ok": false,
  "statusCode": 429,
  "code": "ENTERPRISE_API_LIMIT_REACHED",
  "message": "…",
  "path": "/enterprise/v1/gis/buffer",
  "method": "POST",
  "timestamp": "2026-08-17T09:41:22.104Z"
}

401ENTERPRISE_API_KEY_REQUIRED

What it means

The request arrived without credentials: neither the X-Api-Key and X-Api-Secret pair nor an Authorization: Bearer header was present.

What to do

Send the credentials on every call. When the same key works from curl but not from your client, check that the client is not stripping custom headers across a redirect.

401ENTERPRISE_API_KEY_INVALID

What it means

Credentials were present but did not verify — an unknown public key, a revoked key, or a secret that does not match the one stored for it.

What to do

Confirm you copied the whole secret at creation; it is stored hashed and cannot be read back. If it was lost, create a new key in the console and revoke the old one.

403ENTERPRISE_API_INACTIVE

What it means

The key itself is fine, but the organization has no active API subscription: never activated, suspended, or the term has expired.

What to do

Check the subscription in the console. If it is suspended or expired, only the enterprise desk can reinstate it — retrying will not.

403ENTERPRISE_API_USER_NOT_ASSIGNED

What it means

The email sent in X-Api-User is not an active member of the organization.

What to do

Assign that person in the console, correct the address, or drop the header entirely to attribute the run to the organization owner.

429ENTERPRISE_API_LIMIT_REACHED

What it means

The organization's file count for the current window, plus the files in this request, would cross the package ceiling. The request is refused before the tool runs.

What to do

Wait for the window to clear, spread the load, or move to a larger package. Because the check happens first, nothing was processed and nothing was consumed.

The full code catalog

Every code the GIS and API surfaces bind to an HTTP status.

The codes above are the ones to build client behavior around. This catalog is the lookup table for everything else, grouped by family; the meaning shown is the API's own message text. React to the code — messages are localized and may be reworded.

Message language

Each response carries its message in one language, resolved per request: an x-lang header (or preferredLang in the body), else the Accept-Language header, else Arabic. The code is always the stable, language-independent value.

Generic

422 / 400VALIDATION_ERROR

Validation error.

400FILE_REQUIRED

File is required.

413FILE_TOO_LARGE

File exceeds the maximum allowed size.

404NOT_FOUND

Not found.

409DUPLICATE_VALUE

This field value already exists.

429RATE_LIMIT_EXCEEDED

Too many requests. Please try again later.

500SERVER_ERROR

An unexpected server error occurred.

GIS tool runs

422 / 413GIS_INPUT_REJECTED

This file can't be used: (reason)

502GIS_PROCESSING_FAILED

GIS processing failed. Please check your file and try again.

503GIS_SERVICE_UNAVAILABLE

GIS processing service is temporarily unavailable. Please try again later.

404GIS_TOOL_NOT_FOUND

Unknown GIS tool.

403GIS_TOOL_DISABLED

This GIS tool is currently disabled. Please try again later.

403GIS_TIER_REQUIRED

This tool is available on a higher membership tier.

403GIS_ENTERPRISE_REQUIRED

This tool is available on Enterprise workspaces.

403GIS_NOT_COMMUNITY_MEMBER

You must join the Haiyz community to use GIS tools.

403GIS_TRIAL_LIMIT_REACHED

You have used your 2 free trial runs. Join the Haiyz community to keep using GIS tools.

429GIS_USAGE_LIMIT_REACHED

You have reached your usage limit for this tool. It will reset automatically.

404GIS_FILE_NOT_FOUND

The requested GIS file was not found.

Credentials & subscription

401ENTERPRISE_API_KEY_REQUIRED

API credentials are required (X-Api-Key and X-Api-Secret).

401ENTERPRISE_API_KEY_INVALID

Invalid API credentials.

401ENTERPRISE_API_KEY_EXPIRED

This API key has expired.

401ENTERPRISE_API_KEY_INACTIVE

This API key is not active.

403ENTERPRISE_API_KEY_IP_FORBIDDEN

Requests from this IP address are not allowed for this API key.

403ENTERPRISE_API_KEY_SCOPE_FORBIDDEN

This API key does not have access to this tool.

403ENTERPRISE_API_INACTIVE

This organization has no active API subscription.

403ENTERPRISE_API_USER_NOT_ASSIGNED

This user is not an assigned member of the organization.

403ENTERPRISE_SUBSCRIPTION_INACTIVE

The organization's enterprise tools subscription is not active.

403ENTERPRISE_API_NOT_ENABLED

The API channel is not enabled for this organization.

403ENTERPRISE_TOOL_NOT_ALLOWED

This tool is not enabled for your organization.

Quotas, credits & limits

429ENTERPRISE_API_LIMIT_REACHED

The organization's file quota for the current 72-hour window is exhausted. It will reset automatically.

429ENTERPRISE_CREDIT_LIMIT_REACHED

The organization's credit balance for this period is exhausted.

429ENTERPRISE_MEMBER_CREDIT_LIMIT_REACHED

You have reached your member credit cap for this period.

429ENTERPRISE_API_KEY_CREDIT_LIMIT_REACHED

This API key has reached its credit cap for this period.

429ENTERPRISE_RATE_LIMIT_REACHED

Too many requests. Please slow down and retry.

429ENTERPRISE_CONCURRENCY_LIMIT_REACHED

Too many concurrent runs. Please retry shortly.

413ENTERPRISE_DATA_LIMIT_REACHED

The organization's data volume limit for this period is exhausted.

Idempotency, runs & async jobs

422ENTERPRISE_IDEMPOTENCY_KEY_INVALID

The Idempotency-Key header is invalid (8–255 printable characters).

409IDEMPOTENCY_KEY_REUSED

This Idempotency-Key was already used with a different request.

409REQUEST_IN_PROGRESS

A request with this Idempotency-Key is still being processed.

404ENTERPRISE_RUN_NOT_FOUND

Run not found.

404ENTERPRISE_ARTIFACT_NOT_FOUND

Artifact not found.

404ENTERPRISE_ASYNC_JOB_NOT_FOUND

Async job not found.

409ENTERPRISE_ASYNC_JOB_ALREADY_FINALIZED

This job has already finished and can no longer be changed.

422ENTERPRISE_ASYNC_TOOL_NOT_ELIGIBLE

This tool does not support async large-file jobs.

Dataset, share-link and data-room codes are documented with the Datasets guide at /docs/datasets.

The rolling 72-hour window

How the quota is counted, and when it clears.

Windows tile the timeline from a fixed origin, identically for every organization. There is no per-customer anchor and no drift from a subscription date — boundaries land at the same instants for everyone.
The unit is one file. A run that processes several files spends several, and a request that carries no file at all — the JSON reprojection — counts as one.
The check is a sum over the current window, made before the tool is scheduled. If the incoming files would cross the ceiling, the call returns ENTERPRISE_API_LIMIT_REACHED and nothing runs.
Only successful runs are recorded, so a rejected or failed call does not consume the window.
Because the boundaries are deterministic, your client can compute the reset itself: the current window began at the last multiple of 72 hours and clears exactly 72 hours after that.

Files per rolling 72-hour window, by package.
Package	Files / 72h
Starter	1,000
Pro	5,000
Ultra	20,000

Every key shares one window

The ceiling belongs to the organization, not to a key or a member. Adding keys separates environments; it does not add quota. Usage per key, per member and per tool is broken down in the console.

Size ceilings

How much one call can carry, and what happens when the file is larger than that.

Direct request ceiling

50MB

Asynchronous ceiling

500MB

Upload window

30min

A single synchronous request accepts up to 50 MB of input. Past that the connection is the bottleneck rather than the engine, which is what the asynchronous path exists to get around.
Work submitted as a job accepts up to 500 MB of input — the same tools, run off the request instead of inside it.
A job's upload slot stays open for 30 minutes. Confirm the upload inside that window or the slot expires and the job is abandoned.

Jobs, attempts and backoff

What happens to work that runs off the request, and the retry policy your own client should mirror rather than fight.

7states: A job moves through a fixed set of states, from awaiting upload to a terminal outcome. That state is the only reliable progress signal — elapsed time says nothing about how far along a job is.
8queues: Work is dispatched across dedicated queues, so a long geoprocessing job never sits behind unrelated platform work.
3attempts: A failing job is retried up to 3 times in total before it is marked failed. Your client does not need to resubmit in between.
2,000ms backoff: Retries wait 2000 milliseconds and back off from there. A client that retries faster than this adds load without getting an answer sooner.

Cancellation

A cancel is honoured at 4 checkpoints — not instantly.

01
At pickup
Before the worker takes the job off the queue at all.
02
Before quota is reserved
Before the run reserves anything against the organization's window.
03
Before the engine call
After preparation, before the geoprocessing call is dispatched.
04
Before the output is stored
After the engine returns, before the result is written and recorded.

A call already in flight runs to completion

The worker cannot abort a geoprocessing call once the engine has started it. Cancelling stops the job at its next checkpoint, which on a heavy run may be after the compute has finished — the result is simply never stored or recorded.

What your client should do

Half of a good integration is knowing which failures are permanent.

401

Do not retry. The credentials are missing or wrong, and repeating the call fails identically. Fix the headers, then send the request again.

403

Do not retry. Either the subscription is inactive or the attributed member is not assigned — both need a change in the console, not another attempt.

429

Retry after the window clears, not immediately. The reset instant is computable: the window is 72 hours long and its boundaries are fixed.

5xx / network

Retry with backoff and cap the attempts. Mirroring the platform's own policy — 3 attempts, starting from 2000 ms — is a reasonable default.

Open the console Talk to the enterprise desk

Usage against the current window — per member, per tool and per key — is shown in your organization's console.

{ "ok": false, "statusCode": 429, "code": "ENTERPRISE_API_LIMIT_REACHED", "message": "…", "path": "/enterprise/v1/gis/buffer", "method": "POST", "timestamp": "2026-08-17T09:41:22.104Z" }

Files per rolling 72-hour window, by package.

Package

Files / 72h

Starter

1,000

Pro

5,000

Ultra

20,000