Errors & limits
Error codes, rate limits, calling hours and quotas.
Error format
An error comes back with a fitting HTTP status and a JSON body: {"error":"CODE","message":"…"}. Rely on error; message is for humans and is sometimes the same as the code. A validation error (VALIDATION) carries issues instead, with path and message per field. INVALID_JSON, REQUEST_TOO_LARGE and INTERNAL come without message.
HTTP/1.1 409 Conflict
{ "error": "REVISION_CONFLICT", "message": "current revision is 3" }
HTTP/1.1 400 Bad Request
{ "error": "VALIDATION", "issues": [ { "path": "goal", "message": "Too small: expected string to have >=1 characters" } ] }
HTTP/1.1 429 Too Many Requests
Retry-After: 60
{ "error": "RATE_LIMITED", "message": "RATE_LIMITED" }Error codes
| HTTP | error | Meaning |
|---|---|---|
| 400 | VALIDATION | The body failed validation. Details in issues. |
| 400 | INVALID_JSON | The body is not valid JSON. |
| 400 | INVALID_NUMBER | Not a dialable Israeli number. |
| 400 | BAD_DECISION | The decision is not one of the consultation’s options. |
| 400 | BAD_WEBHOOK_URL | The webhook URL is not public https on port 443. |
| 401 | UNAUTHENTICATED | Missing, wrong, expired or revoked key. |
| 403 | INSUFFICIENT_SCOPE | An API key cannot use this endpoint. |
| 403 | LEGAL_ACCEPTANCE_REQUIRED | Accept the current terms on the site. |
| 403 | CALLS_PAUSED | Calls are paused on this account. |
| 403 | NO_PLAN | No active plan. |
| 403 | QUOTA_EXHAUSTED | No minutes left this month (at least 30 seconds are needed). |
| 403 | QUOTA_HELD | The remaining minutes are held by other queued or active calls. |
| 403 | DO_NOT_CALL | The number asked not to be called. |
| 404 | TASK_NOT_FOUND / CONSULTATION_NOT_FOUND | No such task or consultation on this account. |
| 409 | REVISION_CONFLICT | The task changed. Read it again and resend with the current revision. |
| 409 | CALL_NOT_ACTIVE | The task has ended, or the action does not apply to it. |
| 413 | REQUEST_TOO_LARGE | The body is larger than 100 KB. |
| 429 | RATE_LIMITED | Too many requests this minute. Wait for Retry-After. |
| 429 | DAILY_CALL_LIMIT | You reached the plan’s daily call count. |
| 429 | NUMBER_DAILY_LIMIT | This number has had enough calls in the last 24 hours. |
| 429 | TOO_MANY_AGENTS | There are already 20 active keys and agents. |
| 500 | INTERNAL | Something failed on our side. Retry with the same idempotency_key. |
Rate limits
- Per account, per minute: 600 read requests (GET) and 120 write requests. Shared by all keys and agents on the account.
- Consultation answers and cancel are never limited, so a live call is always controllable.
- Over the limit:
429 RATE_LIMITEDwithRetry-After: 60.
Idempotency
POST /v1/call-tasksrequiresidempotency_key. The same key again returns200with the existing task andcreated: false, even if the rest of the body differs. So after a timeout or a 500, resend with the same key.- For instructions,
idempotency_keyis optional and returns the original result on a resend. - For consultation answers the first one wins; later ones get conflict or expired.
Numbers
Israeli numbers only: mobile 05X, landline 02/03/04/08/09, and 07X, each followed by 7 digits. Local or international format, with spaces or dashes. Anything else: 400 INVALID_NUMBER, before anything is counted. No calls abroad and no inbound calls.
Calling hours
| Day | Hours (Israel time) |
|---|---|
| Sun–Thu | 08:00–21:00 |
| Fri | 08:00–14:00 |
| Sat | No calls |
A task created outside these hours is queued, and not_before shows when it will be dialed. A task not dialed within 24 hours of not_before expires (task.expired). A retry that would fall outside the hours is not made.
Daily limits
| Plan | Calls per day |
|---|---|
| Trial (10 minutes) | 10 |
| Personal | 30 |
| Regular | 80 |
| Business | 200 |
- The day follows Israel time. Failed, cancelled and expired tasks are not counted.
- Per phone number: up to 3 calls from one account and 5 from all accounts together in 24 hours. Retries count.
Duration and billing
max_duration_sfrom 30 to 1800 seconds, default 300, and never more than the minutes left on your plan.- Billing is per second from when the call is answered. Unanswered calls and voicemail are not counted.
- Studio plans per month, a business agent with minutes included: Start ₪499 (100 min, 1 agent; WhatsApp ₪59 extra), Grow ₪699 (250 min, WhatsApp included), Pro ₪999 (400 min, 2 agents, WhatsApp included); each more active agent ₪199. Studio packs: ₪99 for 30 minutes, ₪179 for 60, ₪329 for 120. API plans, for calls from your own agent: Personal ₪49 (30 min), Regular ₪129 (100 min), Extended ₪299 (300 min); packs ₪29 for 30 minutes, ₪55 for 60, ₪99 for 120. New accounts get 10 trial minutes, with no time limit. See pricing (Hebrew).
Versioning
All endpoints are under /v1. New fields and event types may be added within v1, so ignore fields or types you do not recognise and do not rely on field order. Updates are posted in the changelog (Hebrew).