Skip to navigation

Errors and Rate Limits

View as Markdown

Lead Receive API errors use standard HTTP status codes and machine-readable code values where available.

Common errors

CodeHTTP statusMeaning
AUTH_FAILED401Missing, invalid, or expired API key.
INVALID_REQUEST400Request body or lead format is invalid.
DYNAMIC_VARIABLES_INVALID400No lead in the request was accepted, and at least one was rejected by the dynamic variables check. On a 207 response the same code marks each lead rejected by this check in data.rejectedLeadDetails.
INSUFFICIENT_CREDITS402The company has zero or negative credits. No leads were queued.
AGENT_NOT_FOUND404Agent does not exist, is inactive, or does not belong to the company.
RATE_LIMIT_EXCEEDED429Too many requests for the agent.
INTERNAL_ERROR500SimZ could not complete the request.
BILLING_CHECK_FAILED503SimZ could not verify the credit balance. The request fails closed and no leads were queued.
DYNAMIC_VARIABLES_CHECK_FAILED503SimZ could not check the lead’s dynamic variables. The request fails closed and no leads were queued.
BATCH_NOT_FOUND404Batch does not exist.
FORBIDDEN403Batch belongs to another company.
BATCH_NOT_PAUSABLE409Batch is not in a dispatchable state.
BATCH_NOT_RESUMABLE409Batch is not paused.
BATCH_NOT_CANCELLABLE409Batch is terminal or not in paused, queued, or processing status.
NO_ACCEPTED_BACKLOG409No accepted leads remain waiting to dial. Applies to pause and resume only.

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, and BATCH_NOT_CANCELLABLE mean the batch is not in the right lifecycle state for that action. Check status with GET /api/lead-receive-service/agent/batches/{batchId} before retrying.
  • NO_ACCEPTED_BACKLOG applies to pause and resume only. cancel succeeds even when no accepted backlog remains.
  • pause-all and cancel-all skip 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.

{
"success": false,
"code": "INSUFFICIENT_CREDITS",
"message": "Leads were not queued because this account has insufficient credits. Please add credits before submitting leads for calling.",
"data": {
"agentId": "agent-id",
"companyId": "company-id",
"totalCredits": -10,
"totalLeads": 25,
"acceptedLeads": 0,
"rejectedLeads": 25,
"reason": "account_credit_balance_too_low",
"actionRequired": "add_credits"
}
}

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".

{
"success": false,
"code": "BILLING_CHECK_FAILED",
"message": "Unable to verify account credit balance. Leads were not queued. Please try again shortly.",
"data": {
"agentId": "agent-id",
"companyId": "company-id"
}
}

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.