The API uses standard HTTP status codes. Errors return a JSON body with a
statusCode and a human-readable statusMessage.
Status codes
| Code | Meaning | Common cause |
|---|---|---|
200 | Success | The request succeeded. |
400 | Bad request | A required parameter is missing or invalid (for example an unknown format, or a diff request missing jobId1/jobId2). |
404 | Not found | The scraper ID does not exist, or a referenced job is not found or has not completed. |
429 | Too many requests | You exceeded your plan's monthly allowance for that endpoint. |
The empty result case
A request can succeed with no data. If a scraper exists but has never completed a
run, search and results endpoints return 200 with an empty data array:
json
{
"data": [],
"pagination": { "total": 0, "page": 1, "take": 10, "totalPages": 0, "hasMore": false }
}
Treat empty data as a normal state, not an error. In an agent, return "I could
not find any matching records" rather than throwing. It usually means the query
matched nothing, or the scraper has not run yet.
Handling errors in code
js
const res = await fetch(url)
if (res.status === 429) {
// Back off or tell the user the quota is exhausted.
}
if (!res.ok) {
const { statusMessage } = await res.json()
throw new Error(`Trawley API ${res.status}: ${statusMessage}`)
}
const { data } = await res.json()