Errors
Error responses use a stable envelope (no stack traces or internal paths):
{
"success": false,
"request_id": "…",
"error": {
"code": "VALIDATION_ERROR",
"message": "Human-readable guidance"
}
}| Code | HTTP | Remediation |
|---|---|---|
| MISSING_API_KEY | 401 | Add Authorization: Bearer tg_api_… |
| INVALID_API_KEY | 401 | Key invalid or revoked — create a new key |
| IDEMPOTENCY_KEY_REQUIRED | 400 | Send Idempotency-Key header |
| IDEMPOTENCY_CONFLICT | 409 | Same key used with a different payload |
| IDEMPOTENCY_IN_PROGRESS | 409 | Retry later; prior request still running |
| VALIDATION_ERROR | 400 | Fix tool parameters or multipart fields |
| AI_FEATURE_NOT_AVAILABLE | 400 | This tool has no AI path — remove useAI or pick a tool with supports_ai on GET /v1/tools |
| FILE_REQUIRED | 400 | Include multipart file field |
| UNSUPPORTED_FILE_TYPE | 415 | Use an accepted MIME type for the tool |
| FILE_TOO_LARGE | 413 | Reduce file size under the tool limit |
| UNSUPPORTED_TOOL | 404 | Use an enabled tool ID from the registry |
| INSUFFICIENT_API_CREDITS | 402 | Buy API credits in the dashboard |
| PRICING_NOT_CONFIGURED | 503 | Gateway pricing missing for this tool (strict mode) — contact support |
| DEVELOPER_API_SUBSCRIPTION_REQUIRED | 403 | Subscribe to TOOLGRID API GATEWAY on /pricing (separate from Business VIP) |
| RATE_LIMITED | 429 | Back off and retry |
| REQUEST_TIMEOUT | 504 | Retry with Idempotency-Key or smaller input |
| OUTPUT_TOO_LARGE | 413 | Output exceeded configured max size |
| EXECUTION_FAILED | 500 | Safe failure; reserved credits are refunded |
| INTERNAL_ERROR | 500 | Retry; contact support with request_id if persistent |
| BATCH_NOT_SUPPORTED | 400 | Tool has batch.supported=false — use POST /v1/execute or another tool |
| BATCH_LIMIT_EXCEEDED | 400 | Too many files or total bytes over tool/job caps |
| JOB_NOT_FOUND | 404 | Wrong job_id or not owned by this API key user |
| JOB_EXPIRED | 410 | Past retention window; files deleted |
| JOB_ITEM_NOT_READY | 409 | Item still queued/running/failed — poll GET /v1/jobs/:id |
| SANDBOX_AI_BLOCKED | 403 | Sandbox cannot use AI paths — set useAI=false |
Auth, validation, rate-limit, and unsupported-tool failures do not reserve API credits. After a reservation, eligible execution failures refund the hold.