HTTP 422 on a Swarme run is usually a field rule, not an auth failure and not a broken quote. Four observed bodies, each after a successful quote on a supported tool, are enough to read the pattern.
The strings, with the slugs that returned them:
- address-label-formatter: Use labeled address lines in key: value form or provide JSON.
- apache-virtual-host-generator: Domain must contain valid ASCII hostname labels.
- backlink-quality-checklist: backlinks must contain between 1 and 1,000 records.
- base64-url-decoder: Enter valid Base64URL input.
Read the body. Fix the named field. Quote again if the 900-second lock expired. Do not rotate the API key. Do not treat 422 as HTTP 419.
Quote can succeed while run still 422s
Docs at https://swarme.io/developers list Search, Describe, Quote, Run. Quote checks price, wallet policy, and that the capability is allowed to proceed. It does not promise that every field will pass execution rules.
Create the key at https://swarme.io/dashboard?tab=developers. /dashboard/developers is 404. Send Authorization: Bearer with capabilities:quote and capabilities:run. Then:
- GET /api/capabilities/{slug} and read execution.machine_run_status.
- POST .../quote with the exact input you will run and "client_type": "api".
- POST .../run with that quote_id and an Idempotency-Key.
uuid-generator accepted empty input {} on that path. The completed run returned 4cd3c7b6-0495-447a-8efd-9a1374f7599c at $0.00 included after a 900-second lock, with idempotency_required_for_client true. The four 422 slugs above quoted, then failed run. Quote status quoted plus run HTTP 422 is a coherent pair. It is not a platform contradiction.
What each of the four strings asks for
Use labeled address lines in key: value form or provide JSON. The formatter did not receive labeled lines or JSON. Empty input is not a labeled address. Describe the slug, then send keys the schema names.
Domain must contain valid ASCII hostname labels. The hostname you sent was not valid ASCII labels. Do not paste a URL with a scheme and path and expect the field to accept it as a hostname. The rule is on the domain value.
backlinks must contain between 1 and 1,000 records. On backlink-quality-checklist, an empty or oversized backlinks array fails. The bounds are 1 and 1,000. Zero records is outside the contract. So is 1,001.
Enter valid Base64URL input. This is not a generic Base64 error. The alphabet is Base64URL. A standard Base64 payload with + and / can fail here even if a decoder elsewhere accepts it.
Other completed slugs (accessibility-statement-generator, add-line-numbers, alphabetizer, article-rewriter-assistant, ascii-table-generator, base64-text-decoder) made it to completed. That does not mean empty input is valid everywhere. base64-text-decoder completing is not a license to send the same payload to base64-url-decoder.
Do not confuse 422 with the nearby codes
| Outcome | What it is |
|---|---|
| HTTP 422 | Field rule after quote. The four strings above. |
| HTTP 419 | Unauthenticated quote. Your secure request token expired. |
| HTTP 401 | Unauthenticated balance. |
| Login toast | Your secure form token expired. Please go back and try again. |
| 404 | https://swarme.io/dashboard/developers is the wrong path. |
| describe_only | 1491 of 1940 tools block quote/run. Not a 422. |
A login CSRF expiry is a form token, not a hostname label. Reloading /en/login will not put 1 to 1,000 records into backlinks. Sending a new key will not turn + into Base64URL.
Wallet $0.00 / metered_observe is not a 422. describe_only is a different stop: 1491 of 1940 tools block quote/run. 439 are supported. 10 are requires_worker. Branch on machine_run_status before you parse a 422.
How to handle 422 in a client
- Log the HTTP status and the exact body string. Do not collapse all 4xx.
- If the body matches a field rule, show that string to the caller. Point at the describe schema for the slug.
- Do not retry the same payload in a loop. The four observed strings did not change on repeat.
- If more than 900 seconds passed, quote again with the corrected input. Reuse of an expired quote_id is a different error than 422.
- Keep one Idempotency-Key per logical attempt. A new key with fixed input is a new attempt.
MCP follows the same gate. POST https://swarme.io/mcp initialize (2025-03-26, Swarme Capability MCP Alpha, 2026.07.15-wallet-alpha) listed 22 tools, including quote and run helpers. swarme_tool_run can still 422. tools/list returning 22 names does not validate your hostname.
Category slugs such as web-seo, security-network, and ai-tools only change search. GET /api/capabilities still caps at 500; paging will not fix Base64URL.
If the 422 is on a file field, stop. pdf-to-word is client_browser / server_receives_file_bytes false. merge-pdf is async_worker / server_receives_file_bytes true. See how to choose a secure online file tool. For pausing an agent when run returns a labeled error, see AI tool routing.