View as Markdown Open in ChatGPT Open in Claude

Error codes and cost reporting

Every refused or failed tool call says why with a stable code and a retry hint, and every tool result says what it cost. Agents can branch on the code instead of parsing English.

How an error looks

A tool result that is JSON keeps its error field and gains error_info:

{
  "error": "pull_ceiling_exceeded",
  "message": "This account has reached its fair-use cap ...",
  "error_info": {
    "code": "pull_ceiling_exceeded",
    "message": "This account has reached its fair-use cap ...",
    "retryable": false,
    "retry_after_s": null,
    "docs": "https://justclaw.it.com/docs/errors#pull_ceiling_exceeded",
    "legacy_error_until": "2027-02-03"
  }
}

Refusals that arrive as plain text (quota and keyless limits, answered before the tool runs) carry the same code in the result's _meta["com.justclaw-it/call"].error_code.

A refusal is still a normal tool result (isError is false, as before): check for error / error_info in the JSON. isError is true only when the tool itself failed unexpectedly (internal_error).

Treat a code you don't know like internal_error and follow its retry_after_s. A null retry_after_s means retrying the same call will not help.

Compatibility (90 days)

The old error values stay exactly as they were until 2027-02-03. After that date error holds the stable code itself. Most errors already do; the changes are not available → not_available, not found → not_found, unknown tool … → unknown_tool, and free-text argument errors → invalid_argument (the text moves to error_info.message). Read error_info.code today and nothing changes for you.

Cost reporting

Every tool result carries _meta["com.justclaw-it/call"]:

field	meaning
`request_id`	id of this call, also sent as the `X-Request-ID` response header; quote it to support
`credits_charged`	credits this call took (0 for free tools)
`credits_refunded`	credits given back because the call was refused or found nothing
`balance`	the account's spendable credits after this call (keyed and signed-in callers)

JSON-RPC batch requests (several messages in one POST) are refused with batch_not_supported before anything is charged; send one message per request.

Account and plan

`key_required`

This tool needs an API key (free, no card). Keyless use covers search_components only. Retrying the same call won't help: fix the call, change plan or wait.

`pro_required`

This tool or option is part of the Pro plan. Retrying the same call won't help: fix the call, change plan or wait.

`out_of_credits`

No credits left for this period. Wait for the refill or upgrade. Retry after the next credit refill (or upgrade).

`ip_daily_free_cap`

The free plan's daily credit cap for your network is used up. Retry after 00:00 UTC (retry_after_s counts down to it).

`revoked`

This API key was revoked. Create a new one on /account. Retrying the same call won't help: fix the call, change plan or wait.

Rate limits and caps

`search_rate_limited`

Too many free discovery calls in the last minute. Retry after 60 seconds.

`search_daily_cap`

Daily free discovery limit reached for this key or network. Retry after 00:00 UTC (retry_after_s counts down to it).

`too_many_requests`

Too many requests from your network. Retry after 60 seconds.

`unavailable_pulls_rate_limited`

Too many get_component calls for ids that are not available. Retry after 60 seconds.

`pull_ceiling_exceeded`

Fair-use cap on distinct components pulled in 12 months reached. Retrying the same call won't help: fix the call, change plan or wait.

`daily_limit`

Daily limit for this tool reached. Retry after 00:00 UTC (retry_after_s counts down to it).

`build_limit`

Daily build limit reached. Retry after 00:00 UTC (retry_after_s counts down to it).

`daily_ai_budget`

The service's daily AI budget for this tool is used up. Retry after 00:00 UTC (retry_after_s counts down to it).

`report_daily_limit`

Daily licence report limit for this account reached. Retry after 00:00 UTC (retry_after_s counts down to it).

Problems with the request

`not_available`

No component with that id is available (missing, or not licence-cleared). Retrying the same call won't help: fix the call, change plan or wait.

`not_found`

Nothing found for that id. Retrying the same call won't help: fix the call, change plan or wait.

`invalid_argument`

An argument has a value the tool does not accept; the message says which. Retrying the same call won't help: fix the call, change plan or wait.

`bad_request`

The request is malformed. Retrying the same call won't help: fix the call, change plan or wait.

`bad_prompt`

The prompt was empty or not usable. Retrying the same call won't help: fix the call, change plan or wait.

`too_many`

Too many items in one call; split it. Retrying the same call won't help: fix the call, change plan or wait.

`nothing_to_check`

The call named nothing to check. Retrying the same call won't help: fix the call, change plan or wait.

`no_components`

No components matched; nothing was built (refunded). Retrying the same call won't help: fix the call, change plan or wait.

`unknown_tool`

No tool with that name. Retrying the same call won't help: fix the call, change plan or wait.

`batch_not_supported`

JSON-RPC batch requests are not supported; send one message per POST. Retrying the same call won't help: fix the call, change plan or wait.

`feature_not_enabled`

This feature is not enabled for this account yet. Retrying the same call won't help: fix the call, change plan or wait.

`file_too_large`

An uploaded file is larger than the limit; send a smaller file. Retrying the same call won't help: fix the call, change plan or wait.

`too_many_files`

Too many files in one report. Retrying the same call won't help: fix the call, change plan or wait.

`too_many_packages`

The files list more packages than one report allows; split them. Retrying the same call won't help: fix the call, change plan or wait.

`unsupported_lockfile`

That file type is not supported; the message lists the supported ones. Retrying the same call won't help: fix the call, change plan or wait.

`parse_failed`

The file could not be parsed (refunded). Retrying the same call won't help: fix the call, change plan or wait.

`parse_timeout`

Parsing took too long; send a smaller file (refunded). Retrying the same call won't help: fix the call, change plan or wait.

`empty_report`

No packages were found in the files (refunded). Retrying the same call won't help: fix the call, change plan or wait.

Temporary service problems

`registry_busy`

The registry is busy; retry shortly. Retry after 5 seconds.

`builder_unavailable`

The builder is temporarily unavailable. Retry after 30 seconds.

`adapt_failed`

Adapting the components failed; retry or change the prompt. Retry after 30 seconds.

`worker_response_too_large`

The result was too large to return. Retrying the same call won't help: fix the call, change plan or wait.

`lost`

The build result expired or was lost; start a new build. Retrying the same call won't help: fix the call, change plan or wait.

`internal_error`

Unexpected server error. Retry once; if it repeats, contact support with the request_id. Retry after 5 seconds.