Errors & Quotas

This public reference explains how Global Mosaic reports account, request, job, and quota problems without exposing customer-only data-category details.

Error response shape

Most failed API responses include a stable error code, a human-readable message, and repair hints:

{
  "status": "error",
  "error": "Invalid API key",
  "error_code": "UNAUTHORIZED_KEY",
  "message": "Invalid API key",
  "repair_hints": [
    "Check that the x-api-key header is present and valid",
    "Create or rotate an API key from the Profile page"
  ]
}

Auth and account errors

Status	Meaning	Action
`401`	API key missing, invalid, expired, or revoked.	Send the `x-api-key` header or rotate the key from Profile.
`402`	The account is not eligible for metered API use.	Upgrade, restore billing, or request access.
`403`	The account cannot use the requested API capability.	Confirm account status, tier, and enabled features.
`404`	The job does not exist or belongs to another key.	Verify the job ID and poll with the same key that started the job.
`429`	The account has exceeded its monthly quota.	Wait for reset or request a quota increase.

Request errors

Status	Meaning	Action
`400`	Malformed JSON body.	Check JSON syntax and content type.
`400`	Missing `layers`.	Include at least one enabled data category.
`400`	Missing `gid` or `geometry`.	Provide a stored boundary identifier or GeoJSON Polygon/MultiPolygon.
`400`	Unsupported parameter.	Use the parameters enabled for your account.
`413`	Request body is too large.	Simplify the geometry or use a stored boundary when possible.

Job status

/invoke starts an async job. /jobs/{job_id} returns the current state.

Status	Meaning	Next step
`queued`	The request was accepted and is waiting to run.	Poll after the suggested delay.
`running`	Work is in progress.	Continue polling with backoff.
`complete`	The job has a result.	Read `result` or follow `result_url`.
`failed`	The job did not complete.	Inspect `error_code`, `errors`, and repair hints.

Retry guidance

Situation	Retry?	Guidance
Network failure before receiving a `job_id`	Maybe	Retry once after de-duplicating in your system.
`202` with a `job_id`	No new invoke	Poll the existing job.
`400` validation error	No	Fix the request before retrying.
`401`, `402`, or `403`	No	Fix key, account, or entitlement state first.
`429` quota exceeded	No immediate retry	Wait for reset or request more quota.
`500` or `502`	Yes, carefully	Retry once; if it repeats, contact support with the job ID.

Quota model

Usage is metered by account and API key.
Quotas reset on the account's billing or plan interval.
Successful /invoke responses include usage metadata so clients can monitor remaining capacity.
Quota failures include the attempted invocation count, quota limit, tier, and repair hints.

Customer accounts should log job_id, request timestamp, selected category names, and quota metadata for support and billing review.