Error codes
Every error returns { error: { code, message, doc_url, retryable } }. Retry only when retryable is true.
- invalid_inputHTTP 400 · don't retry
The request body or a field is missing or malformed.
Read
message, fix the field it names and send again.- unauthenticatedHTTP 401 · don't retry
No valid key or session was sent, or the key was revoked.
Send
Authorization: Bearer <key>with an active key.- forbiddenHTTP 403 · don't retry
You're signed in but your role can't do this.
Ask an org owner.
- not_foundHTTP 404 · don't retry
The thing you asked for doesn't exist or isn't yours.
Check the ID.
- rate_limitedHTTP 429 · retry
Too many requests in a short time.
Wait and retry. Limits are in the
RateLimit-*headers.- invalid_tokenHTTP 401 · don't retry
A sign-in link or invite is invalid, used or expired.
Request a new link.
- invalid_codeHTTP 400 · don't retry
The phone verification code is wrong or expired.
Request a new code.
- phone_in_useHTTP 409 · don't retry
This phone number is already verified on another account.
Use a different number or sign in to the other account.
- email_unverifiedHTTP 403 · don't retry
The email address isn't verified yet.
Open the sign-in link we emailed.
- phone_unverifiedHTTP 403 · don't retry
An org needs a verified phone number first.
Verify your phone, then create the org.
- ip_not_allowedHTTP 403 · don't retry
The agent key has an IP allowlist and this request came from elsewhere.
Call from an allowed IP or update the allowlist.
- unknown_toolHTTP 404 · don't retry
No tool with that ID or slug.
List tools with
GET /v1/tools.- unknown_task_typeHTTP 400 · don't retry
Not one of the seven task types.
List them with
GET /v1/task-types.- credits_frozenHTTP 403 · don't retry
Arettic has frozen this org's credits while we look into something on the account.
Email support. Reads still work; purchases resume once the freeze is lifted.
- insufficient_creditsHTTP 402 · don't retry
The org's credit balance can't cover this purchase.
Top up credits or lower
max_price.- over_budgetHTTP 402 · don't retry
The agent's monthly budget can't cover this purchase.
Raise the budget or wait for the next UTC month.
- approval_requiredHTTP 202 · don't retry
The purchase is over the agent's approval threshold or budget.
Retry with
approval_idafter an owner approves. Approvals expire in 24 hours.- approval_expiredHTTP 409 · don't retry
The approval is older than 24 hours.
Request a new approval.
- approval_rejectedHTTP 403 · don't retry
An owner declined this purchase.
Don't retry it; ask the owner, or change the request.
- trial_limitHTTP 429 · retry
Orgs that haven't topped up yet can spend up to 50 trial credits an hour.
Wait for the hour to pass, or top up to remove the limit.
- approval_mismatchHTTP 409 · don't retry
The tool, input or amount differs from what was approved.
Send exactly the approved request, or request a new approval.
- plan_limitHTTP 402 · don't retry
Your plan's limit on agents, seats or lookups is reached.
Upgrade the plan or wait for the daily reset.
- not_purchasableHTTP 409 · don't retry
The tool is listed for information only, or isn't live yet, so it can't be bought.
Pick a purchasable tool from POST /v1/recommend (purchasable: true).
- price_above_maxHTTP 402 · don't retry
The price for this request (price × inputs) is above your max_price.
Raise max_price, send fewer inputs, or pick a cheaper tool.
- tool_pausedHTTP 409 · don't retry
The tool is paused (outage, loss-making price or provider issue).
Use
fallback: trueor pick another tool fromrecommend.- provider_errorHTTP 502 · retry
The provider failed after one retry. Nothing was charged.
Retry later or use
fallback: true.- check_failedHTTP 200 · don't retry
The result didn't pass the published check. Nothing was charged.
Read
reason; try another tool or fix the input.- request_in_progressHTTP 409 · retry
A request with this idempotency_key is still running.
Retry in a few seconds with the same key to get its receipt.
- provider_quotaHTTP 429 · retry
Your org reached today's call limit for this provider.
Use another tool for the task, or wait for 00:00 UTC.
- aup_limitHTTP 429 · don't retry
The request looks like bulk collection of personal data, which provider terms forbid.
Contact support if this is legitimate research.
- idempotency_conflictHTTP 409 · don't retry
The idempotency key was reused with a different request.
Use a new key for a new request.
- reason_requiredHTTP 400 · don't retry
This action needs a written reason (it goes in the audit log).
Send
reason.- conflictHTTP 409 · don't retry
Something with that slug or email already exists.
Use a different value.
- unverified_emailHTTP 401 · don't retry
Google hasn't verified this email address.
Sign in with an email link instead.
- invalid_stateHTTP 400 · don't retry
The Google sign-in took too long or was opened in another browser.
Start Google sign-in again.
- google_failedHTTP 401 · retry
Google didn't complete the sign-in.
Try again, or use an email link.
- not_configuredHTTP 503 · don't retry
This feature isn't switched on in this environment.
Use another sign-in method.
- invalid_amountHTTP 400 · don't retry
A credit amount is zero, negative or otherwise invalid.
Send a positive whole number of credits.
- capture_exceeds_holdHTTP 409 · don't retry
Internal: a charge was larger than the credits held for it. It was blocked.
Nothing to do on your side; it's logged for us.
- not_a_holdHTTP 409 · don't retry
Internal: a settlement pointed at something that isn't a hold. It was blocked.
Nothing to do on your side; it's logged for us.
- already_settledHTTP 409 · don't retry
This purchase was already charged or refunded.
Fetch the receipt instead of retrying.
- invalid_credentialsHTTP 401 · don't retry
Admin sign-in failed: email, password or code is wrong.
Check all three. Five failures lock the account for 15 minutes.
- lockedHTTP 429 · retry
Admin account locked after too many failed sign-ins.
Wait 15 minutes.
- weak_passwordHTTP 400 · don't retry
Admin passwords need at least 14 characters.
Use a longer password.
- resale_rights_missingHTTP 409 · don't retry
Admin: a tool can't be sold until its provider's resale rights are signed.
Record the signed agreement on the provider, or list the tool as info-only.
- price_missingHTTP 409 · don't retry
Admin: a tool needs a price per success before it can be sold.
Set
price_per_success_credits.- adapter_not_readyHTTP 409 · don't retry
Admin: the tool has no working provider connection (no adapter, or its API key isn't set).
Add the provider key to .env, then run npm run providers:check.
- benchmark_missingHTTP 409 · don't retry
Admin: a tool must be benchmarked in the last 35 days before it can be sold.
Run a benchmark for the tool.
- below_accuracy_floorHTTP 409 · don't retry
Admin: the tool's latest benchmark accuracy is under the 60% floor.
Keep it info-only, or re-run after the provider improves.
- not_disputableHTTP 409 · don't retry
The item wasn't charged, so there's nothing to dispute.
Only charged (passed or partial) items can be disputed.
- dispute_window_closedHTTP 409 · don't retry
Disputes must be opened within 7 days of the purchase.
Contact support if you think this item was charged in error.
- topup_capHTTP 402 · don't retry
New accounts can add up to $200 of credits in their first 14 days.
Top up a smaller amount, or wait until the account is 14 days old.
- confirmation_requiredHTTP 409 · don't retry
Admin: a large manual adjustment needs its amount confirmed.
Send the same amount again in
confirm_credits.- no_saved_cardHTTP 409 · don't retry
Auto-reload needs a saved card, and this org has none.
Top up once with
save_card: true, then turn auto-reload on.- invalid_signatureHTTP 400 · don't retry
A webhook's signature didn't verify, so it was ignored.
Check the webhook signing secret.
- method_not_allowedHTTP 405 · don't retry
That HTTP method isn't supported here (the MCP endpoint takes POST only).
Use the method in the
Allowheader.- last_ownerHTTP 409 · don't retry
An org must keep at least one owner.
Make someone else an owner first.
- payload_too_largeHTTP 413 · don't retry
The request body is over 1 MB.
Send large batches as async jobs of up to 1,000 items.
- internal_errorHTTP 500 · retry
Something went wrong on our side.
Retry. If it keeps happening, check the status page.
- network_errorSDK-side, never sent by the API · retry
SDK: the request never got a response (DNS, connection reset, offline).
Retry with backoff; the SDKs do this for reads and for
execute, whose idempotency key makes a retry safe.- timeoutSDK-side, never sent by the API · retry
SDK: the request hit the client's timeout before a response arrived.
Retry, or raise the client's timeout for long batches (or use jobs for over 25 items).
- connection_failedSDK-side, never sent by the API · retry
MCP package: the local server couldn't reach the hosted MCP endpoint.
Check ARETTIC_API_URL and your network; the call is retried once if it certainly never left.
- abortedSDK-side, never sent by the API · don't retry
SDK: your own AbortSignal cancelled the request.
Nothing to fix; send the request again when you want it.
- http_errorSDK-side, never sent by the API · don't retry
SDK: an HTTP error came back without the API's error body (a proxy, firewall or load balancer answered). The HTTP status is on the error.
Check ARETTIC_API_URL and anything between you and the API. A 429 or 5xx from a proxy is reported as
rate_limitedorinternal_errorand retried.- unexpected_redirectSDK-side, never sent by the API · don't retry
SDK: the server answered with a redirect, which the SDKs never follow (it could leak your key).
Check ARETTIC_API_URL: it should be https://api.arettic.com with no path.