API reference
Errors and limits
Validation, account access, conflicting requests, and active jobs.
{
"error": "We couldn't create the crawl job. Please correct the fields below and try again.",
"details": {
"fieldErrors": {
"targets": [
"Select at least one target."
]
},
"formErrors": []
}
}Errors use an error string with optional details, not a uniform nested error.code object.
| HTTP status | Meaning | Response |
|---|---|---|
| 400 | Invalid JSON, fields, UUID, or idempotency header. | Correct the request; inspect optional details.fieldErrors and details.formErrors. |
| 401 | Missing or invalid account bearer token. | Check supplied credentials with the team. |
| 404 | Missing or unowned job. | Check job ID and account. |
| 409 | Changed request under a reused key, or result not ready. | Restore the original request for replay. For intentionally changed work use a fresh key. If the result is not ready, poll the existing job until terminal status. |
| 429 | Five active jobs already exist for the account. | Wait for jobs in queued, running or finalizing states to finish. This is separate from request-rate limits and the deployed maximum runCount; no guaranteed Retry-After header is documented. |
| 503 | For example, webhook delivery is not configured. | Contact the team or submit without a webhook using a fresh key for changed work. |
Handle unexpected server errors and network failures without assuming a job was not created. Retain the same key and payload for submission retries. Client polling should be bounded; a timeout does not cancel the server job.