For GET /v1/live/pull, inspect the HTTP status, success, errorCode, and errorMessage together. Save the original response or note that no response arrived. Campaign API writes use a different request and receipt contract.
| Status or message | Next action |
|---|---|
401, Missing API key, invalid or expired Key | Check the Authorization: Bearer ... header and the Key's status and expiry. Correct or replace the credential through its authorized manager. |
403, no data or subscription access | Check the Key's Data permission, selected scope, and organization. Ask the organization administrator to correct access; changing the request ID cannot grant it. |
404, Subscription not found | Confirm the Subscription ID in API Keys → Pull from and the Key's organization. A subscription outside that organization can also be returned as not found; ask its administrator to verify the grant. |
400 or 422, invalid parameters | Correct the named field, limit, mode, or filter combination, then retry a bounded request. |
402, insufficient_balance | Check the organization's available billing funds before retrying. |
402, entitlement_required | The source is priced on application and cannot be bought self-serve yet; adding funds will not help. Send hello@humanbased.ai the dataset_id from the response. |
429, Too many requests | Wait the seconds given in Retry-After, then continue more slowly. See Rate limits. |
503 | Keep the error and request context, wait for service recovery, then retry within the intended mode and scope. Escalate repeated errors. |
A request without a Key can return:
{"data": null, "success": false, "errorCode": 401, "errorMessage": "Missing API key"}If success is true but data.items is empty, authentication succeeded. Check whether records have reached delivery, whether the subscription and filters include them, and whether incremental mode simply has no new records. The read guide distinguishes replay from incremental delivery.
If no response arrived
First identify the mode used. With from=beginning, retry the same bounded request and cursor when permitted, then keep only a complete response; replay does not advance the shared incremental position. A default incremental request may already have advanced that subscription's shared position and incurred a charge even when its response was lost. Do not assume a second incremental request will return the same page. Reconcile from the subscription's already acquired range using replay and saved record IDs, then decide whether to continue incremental reading. Keep the request time, Subscription ID, filters, and last locally saved IDs for support.
For a persistent error, send support the environment, request time, path, HTTP status if received, sanitized error, read mode, and a redacted subscription scope. Never send the complete Key. See credential setup, API fields, and organization billing.