Reference

Errors

An error answer tells you what went wrong and what to do. Over REST you get an HTTP status plus a JSON body. Over MCP the same body comes back as a tool result with isError set, and its text starts with HTTP and the status.

The error body

json

{
  "errors": [
    {
      "code": "WALLET_INSUFFICIENT_BALANCE",
      "message": "Insufficient wallet balance. Top up to continue.",
      "correlationId": "[ID]"
    }
  ]
}

Switch on errors[0].code. It is stable, the message is for people. Put the correlationId in every message to support: it finds the exact call.

A wallet stop (402) can also carry reserveMicros, availableMicros, missingMicros. Amounts end in Micros: 1,000,000 is EUR 1.

Statuses

Status	Meaning	What to do	Routes that name it
400	The request is not valid.	Read the message. Fix the field it names.	2
401	The key is missing, wrong or revoked.	Send the header `Authorization: Bearer YOUR_KEY` with the whole key.	all
402	The wallet is too low. The code says which case.	Top up, then repeat. Do not retry before.	12
403	The key may not do this. A Read key tried something only a Full key may do.	Use a Full key for this call.	none
404	The thing does not exist in your account.	Check the id. A Read key lists your groups (`GET /api/scraper/group/list`) and scrapers (`GET /api/scraper/list`). Other accounts’ data answers 404 too.	none
409	The thing is busy or the call clashes with another.	Wait, then retry. Use the code to see why.	none
413	The body is too big.	Send less, or send a file with `curl -T`.	none
429	Too many calls.	Wait the seconds in `Retry-After`, then retry slower.	any route
500	Something broke on our side.	Retry once. If it stays, send us the `correlationId`.	all
503	We cannot do this right now (for example an export cannot be built).	Wait a little and try again.	none

“Routes that name it” counts, among the 160 routes a Read or Full key can call, the routes whose API reference entry lists this status. A status can still come back from a route that does not list it.

The two wallet stops (402)

Both mean the same thing for you: the wallet is too low. Top up, then repeat the call. Nothing is lost and nothing was charged for the call that stopped.

Code	When
`WALLET_INSUFFICIENT_BALANCE`	Any paid call: the wallet has no balance and no free requests.
`FLOW_RUN_SERVER_WALLET_LOW`	Starting a match run: the available balance is below the most the run can cost. The answer says how much is missing.

json

{
  "errors": [
    {
      "code": "FLOW_RUN_SERVER_WALLET_LOW",
      "message": "Matching did not start: top up and run again.",
      "reserveMicros": 1932750,
      "availableMicros": 500000,
      "missingMicros": 1432750
    }
  ]
}

See Wallet and billing and Run a match.

Error codes

These codes appear in the API reference. Only codes you can act on are listed.

Code	Status	Meaning	What to do	More
`WALLET_INSUFFICIENT_BALANCE`	402	The wallet has no balance and no free requests left.	Top up, then repeat the call. Retrying without a top-up gives the same answer.	Wallet and billing
`FLOW_RUN_SERVER_WALLET_LOW`	402	A match run did not start: the available balance is below the most the run can cost. Nothing is charged.	Top up at least `missingMicros`, then start the run again.	Run a match
`IDEMPOTENCY_KEY_REQUIRED`	400	The call needs an idempotency key and none was sent.	Send a new unique `Idempotency-Key` (or `idempotency_key` for a tool).	API basics
`IDEMPOTENCY_KEY_REUSED`	409	The key was already used for a different request.	Use a new key for a new request. Reuse a key only to retry the same request.	API basics
`ARGS_HASH_MISMATCH`	409	The key was used for a different request.	Use a new key.	API basics
`IDEMPOTENCY_IN_FLIGHT`	409	The same call is still running.	Wait a second and retry with the same key.	API basics
`MCP_REQUEST_IN_PROGRESS`	409	The same tool call is still running.	Wait, then ask again with the same key.	Connect your assistant (MCP)
`OWN_MATCH_RUNNING`	409	A match run of this group is running, so the setup cannot be saved now.	Wait for the run to end, then save again with the same key.	Run a match
`SCRAPER_RUN_IN_PROGRESS`	409	A scraper of this group is running.	Wait for it to end, then try again with the same key.	Runs and errors
`OTHER_GROUP_MATCHING`	409	Another group of yours is matching at the moment.	Wait for that run, then save again with the same key.	Run a match
`RUN_STILL_ENDING`	409	A stopped run is still closing down.	Retry after 5 seconds.	Runs and errors
`SCRAPER_RUN_ACTIVE`	409	The scraper is running.	Stop it with a Full key (`GET /api/scraper/\{id\}/stop`), then repeat the call.	Runs and errors
`GROUP_NOT_FOUND`	404	The group is not in your account.	Check the group id (a Read key lists your groups: `GET /api/scraper/group/list`). Groups of other accounts always answer like this.	Groups
`SCRAPER_NOT_FOUND`	404	The scraper is not in your account.	Check the scraper id (a Read key lists your scrapers: `GET /api/scraper/list`).	Runs and errors
`NOT_A_FILE_SCRAPER`	400	You sent a file to a scraper that is not an upload scraper.	Use the id of an upload scraper.	Upload a file
`KEY_COLUMN_REQUIRED`	400	An add-mode upload needs a key column.	Send `keyColumn`.	Upload a file
`FILE_TOO_LARGE`	413	The file is too big for one call.	Send the file as the request body with `curl -T` (it sets the file size), or save Excel as CSV.	Upload a file
`PAYLOAD_TOO_LARGE`	413	The request body is too big.	Send less in one call.	Upload a file
`EXPORT_TOO_LARGE`	400	The export would hold more rows than one file may.	Narrow the filters or export in parts.	Exports and delivery
`EXPORT_NO_MATCHED_RUN`	404	The group has no finished match run to export.	Run a match first.	Results and review
`EXPORT_DISK_LOW`	503	Exports cannot be built right now.	Try again shortly.	Exports and delivery
`WEBHOOK_URL_REFUSED`	400	The webhook address is not allowed: it must be https, public, and carry no login.	Use a public https address.	Exports and delivery
`WEBHOOK_OWNER_ONLY`	403	The group is shared with you, so only its owner can change the webhook.	Ask the owner.	Shared groups
`MCP_JOBS_BUSY`	429	Your account already runs the number of long jobs it may run.	Wait for `Retry-After` or cancel a job.	Connect your assistant (MCP)
`MCP_QUICK_BUSY`	429	Too many calls at the same moment.	Wait for `Retry-After`, then retry.	Connect your assistant (MCP)

When you write to support

Open Support in the portal’s left menu to chat with us, or write to support@scrapewise.ai. Send the HTTP status, the correlationId from the body, the time of the call and what you tried to do.

Last updated 15 September 2026