Troubleshooting

My task never matches

• Check that at least one worker has tags overlapping the task's tags.
• Verify workers are available (not paused).
• Check hard-veto rules that might exclude the worker.
• Call GET /decisions?taskId=... — the decision trace explains why each candidate was accepted or rejected.

I get 401 unauthorized

• Confirm you are using an sk_test_... or sk_live_... key, not a worker token.
• Check that the key has not been revoked in the console.
• Ensure the Authorization: Bearer <key> header is sent (SDKs do this automatically).

I get 429 rate_limited

• Read Retry-After and back off.
• Monitor x-quota-task-rate-remaining before you hit the limit.
• The SDK retries once automatically; if you still see 429s, reduce your call rate.

Webhook signature verification fails

• Pass the raw request body, not parsed JSON.
• Do not decode or re-encode the body before verifying.
• Confirm your webhook secret matches the one in the console.
• Check that the signature timestamp is within 5 minutes of now.

POST /tasks returned 400 validation_error

Common causes:

• priority outside the allowed range.
• tags missing or empty.
• workerId provided on a field that expects it in the body, not the URL.

Pagination loops forever

• Stop when hasMore is false, not when the page is empty.
• Use the nextCursor from the current page, not the previous one.

Still stuck?

• Search the API reference for the exact endpoint.
• Inspect client.decisions.list() for match reasoning.
• Open a docs issue with the page URL and error code.