ToolzerHub Docs

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:

reasonMeaning
no_resultsThe request ran and nothing matched, or nothing exists for what you asked. A search with no matches is the usual case.
record_not_foundThe one record you asked for does not exist, for example a deleted video or an unknown username.
  • When data is null, details is always there. Read details.message before assuming something broke.
  • A failure is never data: null. A failed request has an error status and an error body, 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": {}
  }
}
FieldTypeMeaning
codestringStable machine-readable code for the failure
statusnumberThe matching HTTP status code
messagestringHuman-readable description of what went wrong
retryablebooleanWhether retrying the same request could succeed
detailsobjectOptional extra context, shape varies by error

Error codes

CodeTypical meaning
INVALID_REQUESTThe request was malformed — a missing or invalid parameter
UNAUTHORIZEDThe x-api-key header was missing or invalid
FORBIDDENThe key is valid but not allowed to access this resource
PAYMENT_REQUIREDOut of credits — see Credits
NOT_FOUNDThe requested resource doesn't exist
RATE_LIMITEDToo many requests — see Rate limits
SOURCE_UNAVAILABLEThe upstream public source is temporarily unreachable
SOURCE_ERRORThe upstream public source returned an unexpected error
INTERNAL_ERRORSomething 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.

On this page