Developer API / docs

Error codes

Every error answer names a machine-readable code and links back to this page. Request errors fail the HTTP call. Task errors live inside a job's tasks.

The error shape

{
  "error": {
    "code": "invalid_option",
    "message": "Task 'qr': 'size' is above 2048.",
    "param": "size",
    "doc_url": "https://gigai.tools/developers/errors#invalid_option"
  }
}

Match on code, never on message text. Messages are for humans and may improve. param appears when one field is at fault.

Request errors

invalid_requestHTTP 400

The job graph or a field is malformed. The message names the exact task or field, and param carries it. Fix the request, don't retry as-is.

invalid_optionHTTP 400

A task option failed its schema: unknown name, wrong type, out of range, or a required option is missing. GET /v1/tools shows each tool's schema.

bad_credentialsHTTP 401

Email and password do not match an account.

unauthorizedHTTP 401

The API key or session token is missing, unknown, revoked, or expired. Keys start gk_live_ or gk_test_ and go in the Authorization header as a bearer token.

bad_signatureHTTP 403

A download link's signature is invalid or the link expired. Fetch the file over GET /v1/files/{id} for a fresh URL while the file exists.

email_unverifiedHTTP 403

The account exists but the email is not verified yet. Click the link in the verification mail, then log in again.

ip_not_allowedHTTP 403

This key carries an IP allowlist and the request came from elsewhere. Use a key without an allowlist or add the caller's IP.

missing_scopeHTTP 403

The key is valid but lacks the scope this endpoint needs. Create a key with the default scopes or the one named in param.

invalid_tokenHTTP 404

The email verification link is invalid or expired. Sign up again to get a fresh one.

not_foundHTTP 404

Nothing with that id on this account. Ids are account-scoped: another account's job or file answers 404, not 403.

concurrent_limitHTTP 409

Too many jobs running at once (5 on the free plan). Wait for one to settle, or cancel one.

email_takenHTTP 409

An account with this email already exists. Log in instead.

too_many_keysHTTP 409

The account has 20 keys. Revoke ones you no longer use.

webhook_limitHTTP 409

The plan's webhook endpoint cap is reached (10 on the free plan). Delete an endpoint first.

file_too_largeHTTP 413

An imported file exceeds the plan's byte limit (100 MB free, 10 MB sandbox) or the tool's own limit. Also appears as a task error on import/url fetches.

invalid_emailHTTP 422

That does not look like an email address.

weak_passwordHTTP 422

Passwords need at least 10 characters.

quota_exceededHTTP 429

The monthly task quota is used up (1,000 tool tasks on the free plan). It resets on the first of the month. Sandbox keys never consume it.

rate_limitedHTTP 429

Too many requests. Honor Retry-After and the X-RateLimit-* headers and slow down.

audit_quotaHTTP 429

The daily Site Audit limit is reached (3/day anonymously, 10/day with a free key). Resets at midnight UTC.

agent_quotaHTTP 429

The daily agent planning limit is reached (10 plans/day per account). Resets at midnight UTC. On-device planning in /ask keeps working.

audit_busyHTTP 503

The audit queue is full. Retry in about a minute.

planning_unavailableHTTP 503

POST /v1/agent/plan has no free-tier model capacity right now. Plan locally instead: the /ask page and the MCP tool list both work without it.

Task errors

The job answers 2xx and finishes with status error. The failed task carries the code and message, and the job's remaining tasks are cancelled.

invalid_input

An input file is not what the tool needs: wrong format (checked by content, not extension), corrupt, or password-protected. The message names the file.

needs_two_inputs

merge-pdf got fewer than two inputs.

input_missing

The tasks feeding this one produced no files.

download_failed

An import/url could not be fetched: unreachable, a non-2xx answer, too many redirects, or slower than the 60 second budget.

download_blocked

The import URL resolves to a private or internal address (localhost, LAN ranges, cloud metadata). Only public URLs are fetched, and every redirect hop is checked.

target_unreachable

compress-image cannot reach target_kb even at the lowest quality. The message says what the floor is. Resize smaller or raise the target.

timeout

The engine ran past its time limit for this tool. Try a smaller input.

engine_unavailable

The tool exists in the catalog but this worker build cannot run it right now. Retry later.

engine_failed

The engine failed in a way it could not explain. Retrying is safe. If it repeats with the same file, the file is triggering a bug - tell us.

Was this page helpful?