The error codes, the enterprise's allowance, the size ceilings and a bounded retry policy. Every fixed number on this page is read from the platform's own configuration, not from a rule of thumb.
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_RUN_LIMIT_REACHED",
"message": "…",
"path": "/enterprise/v1/gis/buffer",
"method": "POST",
"timestamp": "2026-08-17T09:41:22.104Z"
}ENTERPRISE_API_KEY_REQUIREDThe request arrived without credentials: neither the X-Api-Key and X-Api-Secret pair nor an Authorization: Bearer header was present.
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.
ENTERPRISE_API_KEY_INVALIDCredentials were present but did not verify — an unknown public key, or a secret that does not match the one stored for it.
Confirm you copied the whole secret when the credential was created; it is stored hashed and cannot be read back. If it was lost, rotate the credential on its application in the Console and use the new secret.
ENTERPRISE_NOT_ACTIVEThe key is valid, but the enterprise it belongs to is suspended or no longer active.
Nothing on your side changes it and retrying fails the same way. An administrator of the enterprise takes it up with the enterprise desk.
ENTERPRISE_API_NOT_IN_PLANThe enterprise's tier carries no API requests, so its keys cannot run tools.
The API comes with the enterprise's tier; talk to the enterprise desk about the tier. Retrying will not help.
ENTERPRISE_API_DAILY_LIMITThe enterprise has made today's API requests — the tier's requests per day, counted across every one of its keys.
Wait for the allowance to refill at midnight UTC. Spreading work across the day avoids it; adding keys does not, because every key draws on the same allowance.
ENTERPRISE_RUN_LIMIT_REACHEDThe enterprise has used its runs of this tool for the current window. The check is made before the tool is scheduled, so nothing ran.
Wait for the window to reset: GET /usage returns the reset time, and every successful response carries it in usage.allowance.resetAt. Other tools keep their own counts.
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
VALIDATION_ERRORValidation error.
FILE_REQUIREDFile is required.
FILE_TOO_LARGEFile exceeds the maximum allowed size.
NOT_FOUNDNot found.
DUPLICATE_VALUEThis field value already exists.
RATE_LIMIT_EXCEEDEDToo many requests. Please try again later.
SERVER_ERRORAn unexpected server error occurred.
GIS_INPUT_REJECTEDThis file can't be used: (reason)
GIS_PROCESSING_FAILEDGIS processing failed. Please check your file and try again.
GIS_SERVICE_UNAVAILABLEGIS processing service is temporarily unavailable. Please try again later.
GIS_BUSYThe processing engine is busy right now. Nothing is wrong with your file — try again in a moment.
GIS_TIMEOUTThe operation took longer than a request may take and was stopped. Try a smaller file, or split the work into parts.
GIS_TOOL_NOT_FOUNDUnknown GIS tool.
GIS_TOOL_DISABLEDThis GIS tool is currently disabled. Please try again later.
GIS_TIER_REQUIREDThis tool is available on a higher membership tier.
GIS_ENTERPRISE_REQUIREDThis tool is available on Enterprise workspaces.
GIS_NOT_COMMUNITY_MEMBERYou must join the Haiyz community to use GIS tools.
GIS_USAGE_LIMIT_REACHEDYou have reached your usage limit for this tool. It will reset automatically.
GIS_FILE_NOT_FOUNDThe requested GIS file was not found.
ENTERPRISE_API_KEY_REQUIREDAPI credentials are required (X-Api-Key and X-Api-Secret).
ENTERPRISE_API_KEY_INVALIDInvalid API credentials.
ENTERPRISE_API_KEY_EXPIREDThis API key has expired.
ENTERPRISE_API_KEY_INACTIVEThis API key is not active.
ENTERPRISE_API_KEY_IP_FORBIDDENRequests from this IP address are not allowed for this API key.
ENTERPRISE_API_KEY_ORIGIN_FORBIDDENRequests from this browser origin are not allowed for this key's application.
ENTERPRISE_API_KEY_SCOPE_FORBIDDENThis API key does not have access to this tool.
ENTERPRISE_TOOL_NOT_ALLOWEDThis tool is not enabled for your enterprise.
ENTERPRISE_NOT_ACTIVEThis enterprise is not active.
ENTERPRISE_API_NOT_IN_PLANThe enterprise's tier does not include API requests.
ENTERPRISE_API_DAILY_LIMITThe enterprise has made today's API requests; the allowance refills at midnight UTC.
ENTERPRISE_RUN_LIMIT_REACHEDThe enterprise has used its runs of this tool for now; they refill when the window resets.
ENTERPRISE_RATE_LIMIT_REACHEDToo many requests. Please slow down and retry.
ENTERPRISE_CONCURRENCY_LIMIT_REACHEDToo many concurrent runs. Please retry shortly.
ENTERPRISE_DATA_LIMIT_REACHEDThe enterprise's data volume limit for this period is exhausted.
ENTERPRISE_IDEMPOTENCY_KEY_INVALIDThe Idempotency-Key header is invalid (8–255 printable characters).
IDEMPOTENCY_KEY_REUSEDThis Idempotency-Key was already used with a different request.
REQUEST_IN_PROGRESSA request with this Idempotency-Key is still being processed.
ENTERPRISE_RUN_NOT_FOUNDRun not found.
ENTERPRISE_ARTIFACT_NOT_FOUNDArtifact not found.
ENTERPRISE_ASYNC_JOB_NOT_FOUNDAsync job not found.
ENTERPRISE_ASYNC_JOB_UPLOAD_NOT_FOUNDNo uploaded file was found at the staging location yet.
ENTERPRISE_ASYNC_JOB_ALREADY_FINALIZEDThis job has already finished and can no longer be changed.
ENTERPRISE_ASYNC_TOOL_NOT_ELIGIBLEThis tool does not support async large-file jobs.
Dataset, share-link and data-room codes are documented with the Datasets guide at /docs/datasets.
What a key may run, counted per enterprise and per tool, and when it refills.
Every key shares one allowance
How much one call can carry, and what happens when the file is larger than that.
Direct request ceiling
Asynchronous ceiling
Upload window
What happens to work that runs off the request, and the retry policy your own client should mirror rather than fight.
A cancel is honoured at 4 checkpoints — not instantly.
At pickup
Before the worker takes the job off the queue at all.
Before quota is reserved
Before the run is counted against the enterprise's allowance.
Before the engine call
After preparation, before the geoprocessing call is dispatched.
Before the output is stored
After the engine returns, before the result is written and recorded.
A call already in flight runs to completion
Half of a good integration is knowing which failures are permanent.
Do not retry. The credentials are missing or wrong, and repeating the call fails identically. Fix the headers, then send the request again.
Do not retry. The key is not allowed this tool, the enterprise is not active, or its tier carries no API — each needs a change in the Console or with the enterprise desk, not another attempt.
Retry after the allowance refills, not immediately. For runs and daily requests the reset time is in the response and in GET /usage; a per-minute or concurrency refusal clears within a minute, so back off and try again.
Retry with backoff and cap the attempts. Mirroring the platform's own policy — 3 attempts, starting from 2000 ms — is a reasonable default.
Runs in the current window — per key and per tool — are on your enterprise's usage page in the Console, and GET /usage returns them.