Errors

Every error is JSON with a human-readable error string. Some carry more:

{
  "error": "Choose a plan and add a card to start your 3 day trial.",
  "code": "onboarding_exhausted",
  "upgradeUrl": "https://app.testorim.com/pricing"
}

error is written for a person and can change. Branch on the status and on code when there is one.

By status

Status	`code`	Meaning	Retry?
`400`	none	The body failed validation (an `issues` array names each problem), a string held a NUL byte, the base URL is a private or internal host, or a saved procedure’s secret would be typed on a host that is not the project’s own	No. Fix the request
`401`	none	No `Authorization` header, or the key is wrong, revoked, expired, or its owner has left the workspace	No
`402`	`onboarding_exhausted`	The account has never subscribed. Choose a plan and add a card	No, until you pay
`402`	`locked`	Runs are paused: the plan ended, the subscription is unpaid or paused, or a payment has been past due for more than 72 hours	No, until you pay
`403`	`read_only_role`	The key’s owner is a `viewer` in its workspace, and this request changes something	No
`403`	`api_key_scope`	API keys cannot make this change. It belongs to the dashboard	No
`404`	none, or `other_workspace`	Not found in the key’s workspace. `other_workspace` adds `orgId` and `orgName` when the key’s owner belongs to the workspace that has it	No
`429`	none	Rate-limited. Carries `Retry-After` and `retryAfter`	Yes, after `Retry-After`
`429`	`plan_quota_exhausted`	The period’s runs, browser minutes or AI execution allowance are used up, or a trial’s runs or minutes are	Yes, once the period renews
`429`	`concurrency_limit`	Your plan’s concurrent runs are all in use. No run was created	Yes, when a run finishes
`500`	none	Something failed on our side	Yes, with backoff

Both 402 codes carry an upgradeUrl pointing at the pricing page. Neither 429 quota code carries Retry-After, because the wait is not a fixed number of seconds.

Runs that are accepted and then do not run

POST /api/runs/trigger answers 202 once the run is created. A few things can still stop it after that, and they are recorded on the run rather than returned by the trigger:

Every test browser is busy. The run waits in line. If no browser frees up within 3 minutes of reaching the front, or 10 minutes in line altogether, it ends with status: "cancelled" and the reason in reportMarkdown.
The plan’s cap was reached by another run in the meantime. The run ends cancelled with the reason.
Setup failed before the browser started. The run ends cancelled with a neutral reason.

A cancelled run has no verdict: overallStatus is null. Poll GET /api/runs/{id} until status is terminal, then read overallStatus.

The `503` code

service_busy (503) is the service’s own capacity, never your quota. The trigger endpoint does not return it: a triggered run waits in line instead, as above.

Retrying safely

Retry 429 and 500, with backoff.
Do not retry 400, 401, 402, 403 or 404: the same request gets the same answer.
A retried trigger is a second run. The API has no idempotency key, so after a trigger that timed out without an answer, check GET /api/projects/{projectId}/runs before sending it again.

Overview

Endpoints

By status

Runs that are accepted and then do not run

The `503` code

Retrying safely

​By status

​Runs that are accepted and then do not run

​The 503 code

​Retrying safely

By status

Runs that are accepted and then do not run

The `503` code

Retrying safely