Errors

Last updated: July 17, 2026

ImageGrid keeps the public error shape intentionally simple. Most failing public endpoints return a JSON object with an error field and an appropriate HTTP status code.

Common error envelope

Most synchronous failures look like this:

{
  "error": "invalid api key"
}

Treat the HTTP status code as the first signal, and the error string as a stable human-readable summary for logs and support workflows.

Every response includes an X-Request-ID header. Record that value with the endpoint, UTC timestamp, account, and relevant asset/job/artifact ID. ImageGrid support can use it to correlate a failing request without needing your API key or a signed URL.

Authentication failures

Typical auth failures:

Recommended handling:

• Do not retry immediately with the same credential.
• Rotate or replace the credential if the caller should still have access.
• Confirm the request is using the API host and the correct header format.

Validation failures

400 Bad Request usually means the request shape or option values are invalid.

Examples:

Handling guidance:

• Fix the payload before retrying.
• Log the endpoint, operation, and error value.
• For job option issues, compare your payload against Operations.

Upload-specific failures

POST /v1/assets can fail for transport, validation, policy, or environment reasons.

Typical responses:

Handling guidance:

• 400 and 415 require a corrected request or source file.
• 403 should be surfaced as a blocked upload, not retried blindly.
• 503 may be transient; retry with backoff if your workflow allows it.
• Those two AV-specific responses only apply when upload scanning is explicitly enabled for the environment.

Not-found responses

404 Not Found means the target resource is unavailable to the current account context or does not exist.

Examples:

Handling guidance:

• Check that the resource ID came from the same account.
• Confirm the resource still exists and was not deleted or expired.
• Do not treat 404 as retryable unless your application has a reason to believe the resource will appear shortly.

Rate-limit, quota, and policy failures

Some public API routes can fail with 429 Too Many Requests when request-rate limits, plan quotas, or account policy deny the action.

Examples include:

• per-IP and per-account route limits
• upload limits
• job creation limits
• jobs that exceed current processing limits (code: "worker_capacity_exceeded")

Handling guidance:

• Treat 429 as a real policy outcome, not a network glitch.
• For route throttles, honor Retry-After, back off, and avoid hot-loop retries.
• If the workflow is legitimate but blocked, review the account's plan and quota state.
• Do not treat normal queue delay as a 429 condition; accepted jobs should be polled until they leave queued.

Artifact download signature failures

GET /v1/artifacts/{id}/download uses the signed URL returned from artifact metadata.

Expired or invalid signature response:

{
  "error": "invalid or expired download signature"
}

Handling guidance:

• Request fresh artifact metadata and use the new download_url.
• Do not cache signed URLs longer than their download_expires_at value.

Server-side failures and retry guidance

500 and 503 indicate a server-side or dependency failure.

Typical public examples:

• failed to load plans
• failed to persist job
• artifact is unavailable
• upload scanning unavailable

Handling guidance:

• Retry transient 5xx responses with backoff and a bounded retry budget.
• Keep asset_id, job_id, and artifact IDs in your logs for support follow-up.
• If retries continue to fail, capture the endpoint, timestamp, and error message for investigation.
• Include the X-Request-ID response header when contacting support.
• upload scanning unavailable is only relevant when AV is explicitly enabled.

Async job failures

Jobs can also fail after they were accepted. In that case, GET /v1/jobs/{id} returns the job object with failure fields instead of a synchronous 4xx or 5xx.

Example:

{
  "id": "00000000-0000-0000-0000-000000000000",
  "operation": "tile",
  "status": "failed",
  "error_code": "operation_invalid",
  "error_message": "tile options are invalid",
  "artifacts": []
}

Handling guidance:

• Treat status: "failed" as a completed async outcome.
• Log both error_code and error_message.
• Retry only when the failure is clearly transient on your side or after you have corrected the input.