Errors and Rate Limits
Lead Receive API errors use standard HTTP status codes and machine-readable code values where available.
Common errors
Batch management errors
Batch control endpoints return success: false with a machine-readable code. These are state conflicts, not transient failures.
BATCH_NOT_PAUSABLE,BATCH_NOT_RESUMABLE, andBATCH_NOT_CANCELLABLEmean the batch is not in the right lifecycle state for that action. Check status withGET /api/lead-receive-service/agent/batches/{batchId}before retrying.NO_ACCEPTED_BACKLOGapplies topauseandresumeonly.cancelsucceeds even when no accepted backlog remains.pause-allandcancel-allskip batches that do not match instead of failing the whole request.
Insufficient credits
Before a lead batch is created, SimZ checks the company’s available credit balance. If the balance is zero or below, the request returns 402 with code: "INSUFFICIENT_CREDITS", the batch is not created, and no leads are queued for calling.
Detect this case programmatically with code: "INSUFFICIENT_CREDITS". Do not retry the same request immediately — add credits to the account first, then resubmit the lead batch.
Billing check failure
If SimZ cannot verify the credit balance, the request fails closed and no leads are queued. This returns 503 with code: "BILLING_CHECK_FAILED".
Dynamic variable errors
A lead is rejected with DYNAMIC_VARIABLES_INVALID when its dynamicVariables contain a key that is not registered, lack a must variable that the outbound prompt refers to, or hold a value that does not fit the type of its variable. The rejected lead lists the keys in unknownVariables, missingVariables, and invalidVariables. Register the variables in the portal under Agents > Variables or correct the request, then resubmit.
If SimZ cannot run the check, the request returns 503 with code: "DYNAMIC_VARIABLES_CHECK_FAILED" and no leads are queued.
See Dynamic Variables for the response fields and examples.
Retry guidance
Retry 429 only after the indicated delay. Retry 5xx with exponential backoff, including 503 BILLING_CHECK_FAILED and 503 DYNAMIC_VARIABLES_CHECK_FAILED. Do not retry 402 INSUFFICIENT_CREDITS until credits have been added. Do not retry validation errors until the request is corrected.
