BoringKit
Pricing
Menu

Account

Sign in

Errors

Handle failures without guessing.

BoringKit returns structured error codes with actionable messages. Retriable errors are distinct from validation and safety rejections.

Error shape

Example
{
  "error": {
    "code": "browser_only_tool",
    "message": "This tool is browser-only; the API publishes metadata but does not accept uploads for this job.",
    "details": {
      "toolSlug": "json-formatter"
    }
  }
}

Common codes

session_required

Sign in before account or billing mutations.

unauthorized

Send a valid bearer key or sign in for account-scoped features.

forbidden

The key, session, or plan does not have permission for this action.

rate_limited

Retry after the indicated delay and reduce request or job concurrency.

invalid_job_payload

Send valid JSON that matches the job request shape.

browser_only_tool

Use the web UI or choose an API-capable worker tool.

invalid_job

Fix tool slug, input kind, options, content type, size limits, or API job support.

download_not_ready

The job is not succeeded or has no downloadable output yet.

download_expired

Output retention ended; run the job again.

url_metadata_failed

URL safety guard rejected the fetch.

plan_upgrade_required

Upgrade to a plan that includes the requested feature, such as AI enhancement.

ai_unavailable

AI enhancement is temporarily unavailable. Continue without enhancement or retry later.

Retry guidance

safe to retry

Network timeouts, 429-style rate limits, and 5xx responses may be retried with the same Idempotency-Key for mutations.

fix before retry

browser_only_tool, invalid_job, unsafe URL, MIME mismatch, size-limit failures, and plan errors need a changed request or account change.

poll instead

download_not_ready means the client should read /jobs/{id} later, not create another job.