Errors
One flat error shape for every endpoint, every error code with its HTTP status, causes and fix, and what to retry. Errors are never charged.
Last updated
Every error from every endpoint has the same flat JSON body, so one switch on code handles all of them:
{
"code": "insufficient_balance",
"error": "not enough credits — buy credits to continue",
"requestId": "req_01JBXV8M0P2R4T6V8X0Z2B4D6F"
}| Field | Present | Meaning |
|---|---|---|
code | always | Stable, machine-readable error code from the table below. |
error | always | A human-readable explanation. Show it or log it; never parse it, since wording can change. |
requestId | almost always | The id of this request. Include it when you contact support. Also sent as the X-Request-Id header. |
retryAfterSeconds | sometimes | How long to wait before retrying. Also sent as the Retry-After header. |
details | sometimes | Structured context, depending on the code (below). |
upgrade | sometimes | On trial_cap_reached: { claimUrl, authorizationServer, scope }. |
Three rules cover most of error handling:
- Errors are never charged. A 4xx means nothing ran or nothing was billed; a 5xx means every attempt failed and the credits held for the call came back.
- Branch on
code, not on the HTTP status alone (three codes share 401, three share 402) and never on the message. - "Not found" data is not an error. A profile that does not exist comes back as a
200withoutput.found: false. Thenot_founderror is about URLs: an unknown SKU or request id.
Error codes
invalid_input
HTTP 400Retry: No — change the requestThe request failed validation before anything ran.
- An input field the API does not declare (inputs are strict: unknown keys are rejected, never ignored)
- A required field is missing, or a value is the wrong type or outside its allowed range
- A routing control is wrong:
preferLatencyUnderMsormaxCreditsis not a positive whole number,maxCreditsis below what this input can be served for (details.cheapestCredits), or the request still sendsmaxCostUsd, whichmaxCreditsreplaced - A malformed
Idempotency-Keyheader (it must be 1–255 visible ASCII characters) - The input itself was rejected as invalid upstream (retrying it unchanged would fail the same way)
What to do: Read details (for schema errors it lists each issue with its path), compare with the API’s inputSchema from GET /v1/apis/{sku}, correct the request and send it again.
key_disabled
HTTP 401Retry: After you actThe key exists but has been disabled.
- Someone on the account disabled it in the dashboard or with
PATCH /v1/api-keys/{id}
What to do: Re-enable it with {"disabled": false} (a full-access key or the dashboard), or switch to another key.
key_expired
HTTP 401Retry: After you actThe key has passed its expiry time.
- The key was created with an expiry (
expiresIn) that has now passed - An agent trial key reached the end of its trial period without being claimed
What to do: Expiry cannot be extended. Create a new key. For a trial key, ask a human to open the claim link from the signup response.
insufficient_balance
HTTP 402Retry: After you actThe balance cannot cover the most this call could cost.
- The workspace has fewer credits (bought, welcome and included with a plan) than the most the call can cost (its quote’s
maxCredits) - The account’s keys are paused: the balance stayed empty for more than 48 hours while calls kept being refused
What to do: Buy credits in the dashboard (Settings › Billing), or lower limit so the call can cost less. Paused keys resume on their own once the balance can pay; nothing else needs to change.
payment_failed
HTTP 402Retry: After you actA plan payment was declined, so the plan did not change.
- The card on file was declined for an upgrade, which charges for the rest of the billing period
What to do: Update the card under Billing details in Settings › Billing › Plans, then make the change again. Nothing was charged.
trial_cap_reached
HTTP 402Retry: After you actAn agent trial key has used its whole trial budget.
- The trial key minted by
POST /agent/signupspent itscapCredits
What to do: Relay upgrade.claimUrl from the error body to a human. Once they approve, the same key keeps working on their workspace’s credits, within the spend limit they set.
key_limit_reached
HTTP 402Retry: After you actThe key’s own spend limit is used up for the current window.
- The key has
limitCreditsperdaily,weeklyormonthlywindow (UTC; weeks start Monday), or a lifetime limit
What to do: Wait for windowResetsAt, raise the limit with PATCH /v1/api-keys/{id}, or use a different key. The workspace’s credits are untouched.
forbidden
HTTP 403Retry: No — change the requestThe credential is valid but may not do this.
- The key’s access level is too low: a
viewkey cannot run or quote APIs; arunkey cannot read the balance, usage or keys - A browser-session request came from an origin we do not accept (cross-site request protection)
What to do: Use a key with the access level the endpoint lists, or create one in the dashboard.
insufficient_scope
HTTP 403Retry: After you actAn OAuth access token is valid but was not granted the permission this endpoint needs.
- The app was approved without the scope, for example
wallet:readbut notapis:run - The person who approved it no longer has a role in the workspace that allows it
What to do: Ask for authorization again with the scope from the WWW-Authenticate header (details.requiredScopes lists every scope that works).
restricted_api
HTTP 403Retry: After you actThis API handles sensitive personal data and your account is not approved for it.
- The API is marked restricted and the account has not accepted the permissible-purpose terms or been approved
What to do: Request access and describe your permissible purpose (see Restricted APIs). Other APIs keep working meanwhile.
not_found
HTTP 404Retry: No — change the requestThe thing addressed by the URL does not exist for you.
- An unknown SKU, or one that is planned or deprecated
- A request, result or key id that does not exist or belongs to another account
- A stored result that is not ready yet, has passed its retention window, or belongs to a failed request (
GET /v1/results/{id}) - An agent claim link that is invalid or has expired
What to do: Check the SKU with GET /v1/apis. This code is never used for “the profile you looked up does not exist”: that is a successful call with output.found: false.
idempotency_conflict
HTTP 409Retry: No — change the requestThe `Idempotency-Key` is already bound to a different request.
- The same key was sent with a different SKU, input or routing controls within the retention window
- Two requests with the same new key started at the same moment (the body carries
retryAfterSeconds) - A change was attempted on an API key that has been revoked
What to do: Use a fresh Idempotency-Key for every new call. Reuse a key only to retry exactly the same request.
custom_id_taken
HTTP 409Retry: After you actAnother monitor in this workspace already uses this `customId`.
- A monitor that is not deleted already has the
customIdyou sent (details.monitorIdnames it) - Two requests used the same
customIdat the same moment
What to do: Use another customId, or change the monitor that has it (PATCH /v1/monitors/{id}). Deleting a monitor frees its customId.
workspace_has_balance
HTTP 409Retry: After you actA workspace cannot be deleted while it still holds credits.
- Credits are left in the workspace (
details.balanceCredits)
What to do: Credits are non-refundable: use them, then delete the workspace.
workspace_has_plan
HTTP 409Retry: After you actA workspace cannot be deleted while it is on a paid plan.
- The workspace’s plan is still running, including a plan cancelled for the end of its period or one with an unpaid invoice
What to do: Cancel the plan in Settings › Billing › Plans, then delete the workspace once the plan has ended.
workspace_busy
HTTP 409Retry: After you actA workspace cannot be deleted while money is still moving in it.
- Calls are still running in the workspace
- A card purchase of credits for the workspace may still be paid (up to 24 hours)
What to do: Wait until running calls finish or the pending purchase expires, then try again.
last_workspace
HTTP 409Retry: After you actYou cannot delete your only workspace.
- The caller belongs to no other workspace
What to do: Create or join another workspace first, then delete this one.
last_owner
HTTP 409Retry: No — change the requestA workspace always has exactly one owner, who cannot be demoted or removed.
- The request changes the role of, or removes, the workspace owner
What to do: Change other members instead. To shut the workspace down, the owner deletes it.
unprocessable
HTTP 422Retry: No — change the requestThe request is well formed but cannot be carried out as asked.
- This API cannot serve this particular input (for example a country or format it does not cover)
- Creating an API key when the account already has 100 active keys
What to do: Change the input (or revoke keys you no longer use). Nothing was charged, and the same request gives the same answer, so do not loop on it.
rate_limited
HTTP 429Retry: Yes, with backoffToo many requests in the current window.
- More than 200 requests in 10 seconds on one key, or more than 1,000 requests in a minute on one account
- More than 120 keyless MCP requests in a minute from one IP address
- Too many agent trial keys created from one network in 24 hours, or the daily trial signup budget is spent
What to do: Wait for the Retry-After header (also retryAfterSeconds in the body), then retry with backoff.
internal_error
HTTP 500Retry: Yes, with backoffSomething failed on our side.
- An unexpected server error
What to do: Retry with backoff, reusing the same Idempotency-Key so a retry can never run twice. If it persists, report it with the requestId.
all_sources_failed
HTTP 502Retry: Yes, with backoffThe call could not be answered, even after automatic retries.
- Every attempt timed out, errored, was rate limited or blocked upstream
What to do: Nothing was charged: the credits set aside for the call came back in full. Retry later with backoff, reusing the same Idempotency-Key; the Network page shows live status.
timeout
HTTP 504Retry: Yes, with backoffThe request passed its deadline before it finished.
- The request ran out of time before it was answered
- A durable request passed its deadline (15 minutes by default) and was expired
What to do: Nothing was charged. For slow APIs send Prefer: respond-async and poll GET /v1/requests/{id}; retry with the same Idempotency-Key.
What details contain
| Code | details |
|---|---|
invalid_input (schema) | The list of validation issues, each with path, message and code. |
invalid_input (maxCredits too low) | { "maxCredits": 10, "cheapestCredits": 17 }: your cap, and the least this input can be served for. |
invalid_input (retired maxCostUsd sent) | { "field": "maxCostUsd", "replacement": "maxCredits" } |
key_limit_reached | limitCredits (the key's limit), spentCredits (spent in the current window), requiredCredits (what the call needs), limitInterval and windowResetsAt. |
workspace_has_balance | { "balanceCredits" }: the credits left in the workspace. Credits are non-refundable, so use them before deleting the workspace. |
idempotency_conflict | { "requestId" } of the request that owns the key. |
| any replayed failure | { "replayed": true, "requestId" } when an Idempotency-Key returned an earlier deterministic error. |
all_sources_failed, timeout, unprocessable and an invalid_input raised because the upstream rejected the input carry no details: which upstream was tried is internal. Quote the requestId and support can see every attempt.
source_unavailable is a legacy code: it was returned when the retired source / allowFallbacks controls excluded every route, and is no longer produced. Keep handling it as "not charged, do not retry unchanged" if your client already does.
Retry or not
| Retry | Codes |
|---|---|
| With backoff, unchanged | rate_limited, internal_error, all_sources_failed, service_unavailable, timeout |
| After you fix something | insufficient_balance, key_limit_reached, trial_cap_reached, key_disabled, key_expired, restricted_api |
| Never unchanged | invalid_input, unauthorized, forbidden, not_found, idempotency_conflict, unprocessable |
Retry with the same Idempotency-Key so a retry can never run twice, and honour Retry-After when it is present. Idempotency and retries has complete retry helpers in TypeScript and Python.
Handling errors in code
type ApiError = {
code: string;
error: string;
requestId?: string;
retryAfterSeconds?: number;
details?: unknown;
upgrade?: { claimUrl?: string };
};
class RetryableError extends Error {
constructor(
readonly body: ApiError,
readonly retryAfterSeconds?: number,
) {
super(`${body.code}: ${body.error}`);
}
}
async function call(sku: string, input: object) {
const res = await fetch(`https://api.primaryapi.com/v1/run/${sku}`, {
method: 'POST',
headers: { Authorization: `Bearer ${process.env.PRIMARYAPI_API_KEY}`, 'Content-Type': 'application/json' },
body: JSON.stringify(input),
});
if (res.ok) return res.json(); // 200 envelope, or 202 snapshot while it runs
const err = (await res.json()) as ApiError;
switch (err.code) {
case 'invalid_input':
throw new Error(`Fix the input: ${err.error}`); // see err.details for every issue
case 'insufficient_balance':
case 'key_limit_reached':
throw new Error(`Out of credits: ${err.error}`); // buy credits or raise the key's limit
case 'trial_cap_reached':
throw new Error(`Ask a human to approve this key: ${err.upgrade?.claimUrl}`);
case 'rate_limited':
case 'all_sources_failed':
case 'service_unavailable':
case 'timeout':
case 'internal_error':
throw new RetryableError(err, err.retryAfterSeconds); // retry with the same Idempotency-Key
default:
throw new Error(`${err.code}: ${err.error} (request ${err.requestId})`);
}
}Reporting a problem
If an error looks like our fault, or data looks wrong, tell us with the requestId:
POST /v1/bug-reportswith{"message": "…", "requestId": "req_…", "sku": "…"}(any key; see Feedback),- the
report_bugtool in the MCP server, - or email [email protected].
Never put an API key in a report.