Responses & Errors
Toolzer Hub API response envelopes: successful data, structured error objects with stable codes and HTTP status, and which errors are safe to retry.
Success responses
Every successful response is wrapped in a data field:
{
"data": {
"...": "endpoint-specific payload"
}
}The schema only guarantees data.products[].product_id for product-shaped
endpoints; everything else is source-specific. See each operation in the
API reference for its exact response shape.
Empty results
A request that runs fine but finds nothing is not an error. You get HTTP 200,
data is null, and details says why:
{
"data": null,
"details": {
"reason": "no_results",
"message": "The request ran successfully, but Threads returned no posts. Threads search matches short, common keywords better than full sentences."
}
}details.reason is one of two values:
reason | Meaning |
|---|---|
no_results | The request ran and nothing matched, or nothing exists for what you asked. A search with no matches is the usual case. |
record_not_found | The one record you asked for does not exist, for example a deleted video or an unknown username. |
- When
dataisnull,detailsis always there. Readdetails.messagebefore assuming something broke. - A failure is never
data: null. A failed request has an error status and anerrorbody, as described below, and is not charged. - A request that runs and finds nothing is charged like any other successful request.
- If a search returns nothing, try a shorter, more common keyword, and check that the id, username or URL is spelled the way the source writes it.
Error responses
Every error response is wrapped the same way, regardless of endpoint:
{
"error": {
"code": "NOT_FOUND",
"status": 404,
"message": "User not found.",
"retryable": false,
"details": {}
}
}| Field | Type | Meaning |
|---|---|---|
code | string | Stable machine-readable code for the failure |
status | number | The matching HTTP status code |
message | string | Human-readable description of what went wrong |
retryable | boolean | Whether retrying the same request could succeed |
details | object | Optional extra context, shape varies by error |
Error codes
| Code | Typical meaning |
|---|---|
INVALID_REQUEST | The request was malformed — a missing or invalid parameter |
UNAUTHORIZED | The x-api-key header was missing or invalid |
FORBIDDEN | The key is valid but not allowed to access this resource |
PAYMENT_REQUIRED | Out of credits — see Credits |
NOT_FOUND | The requested resource doesn't exist |
RATE_LIMITED | Too many requests — see Rate limits |
SOURCE_UNAVAILABLE | The upstream public source is temporarily unreachable |
SOURCE_ERROR | The upstream public source returned an unexpected error |
INTERNAL_ERROR | Something went wrong on Toolzer Hub's side |
Check retryable before you retry
SOURCE_UNAVAILABLE and some INTERNAL_ERROR responses are typically
retryable: true — a short backoff-and-retry is reasonable. Treat
INVALID_REQUEST, UNAUTHORIZED, FORBIDDEN, and NOT_FOUND as not
worth retrying without changing the request first.
Credits
How Toolzer Hub API credits work: most routes cost one credit, failed calls cost nothing, and one request checks your remaining balance.
Rate limits
Toolzer Hub API rate limits depend on your plan. What a RATE_LIMITED error looks like, and how to back off and retry instead of hardcoding a limit.