Errors

Organized by what you see, not by cause.

HTTP endpoints

Status	Meaning	What to do
`400`	Bad input. The `message` says what is wrong.	Fix the request. It used no credits.
`401`	Missing or wrong API key.	Send your key in the `X-Auth` header.
`403`	The plan does not allow the request. The number limit is full, or the plan is Free and the request is about webhooks.	Remove numbers, or change to a larger plan.
`404`	The number is not monitored, no webhook is saved, or no numbers were submitted yet.	Check the number and the path. Submit numbers before you read the schedule.
`429`	More than 60 write requests in one minute.	Wait one minute. Then send the request again.
`502`	CallerAPI could not connect to your webhook endpoint, or the endpoint did not reply to the test event in 10 seconds.	Make your endpoint reply with a 2xx status in 10 seconds.
`503`	Monitoring is not available at this time.	Send the request again later.

Every error body is {"status": "error", "message": "..."}. A 401 for a missing or wrong key is different. Its body is {"error": "Missing API key"} or {"error": "Invalid API key"}.

Error messages

Status	`message`	Cause
`400`	`invalid request body`	The body is not valid JSON, or a field has the wrong type.
`400`	`send at most 100,000 numbers per call`	Too many numbers in one submit request. Split the list.
`400`	`send the number in E.164, like +14155552671`	The `{phone}` in the path is not a valid E.164 number.
`400`	`unknown status filter`	`status` is not `pending`, `clean`, `flagged`, or `unknown`.
`400`	`unknown list`	`list_id` is not a list of this account.
`400`	`this cursor belongs to a different filter`	You changed `status` or `list_id` between pages. Start again without `cursor`.
`400`	`use an https URL on port 443 or 8443 that points at the public internet`	The webhook URL does not follow the rules. See the Webhooks page.
`400`	`choose every N hours or fixed times`	`mode` is not `interval` or `times`.
`400`	`choose 15 or 30 minutes, or 1, 2, 3, 4, 6, 8, 12 or 24 hours`	`interval_minutes` is not an allowed value.
`400`	`choose 1 to 24 different times`	`times` is empty, has more than 24 values, or has the same time two times.
`400`	`use times like 09:00`	A time is not in the `HH:MM` format.
`400`	`choose at least one day`	`weekdays` is empty, has a value that is not 1 to 7, or has the same day two times.
`400`	`the end time has to be after the start`	`end` is the same as `start` or before it.
`400`	`unknown timezone`	`timezone` is not an IANA time zone.
`400`	`no check falls between the start and end time with this interval. Widen the hours or pick a shorter interval`	No check fits between `start` and `end`.
`400`	`no check falls in the next week`	The schedule has no check in the next 7 days.
`401`	`missing account`	The account for this key was not found. Contact support.
`403`	`this plan monitors at most N numbers`	The submit request goes over the number limit. CallerAPI added no numbers. See the Billing and limits page.
`403`	`webhooks are not included on the free plan`	The account is on the Free plan.
`404`	`not found`	The number is not monitored, or no numbers were submitted yet.
`404`	`no webhook is saved`	Save a webhook URL first.
`429`	`too many writes. Wait a minute and try again.`	More than 60 POST, PUT, or DELETE requests in one minute.
`502`	`the endpoint did not respond`	The connection to your endpoint failed, or it did not reply in 10 seconds.
`503`	`monitoring unavailable`	A temporary problem on the CallerAPI side.

Invalid numbers

A submit request does not fail for an invalid number. CallerAPI puts the number in invalid with a reason and adds the other numbers.

`reason`	Cause
`malformed`	CallerAPI cannot read the input as a phone number.
`invalid_number`	The number is not valid for its country.
`unknown_country`	The input has no `+` and `default_country` is missing, or the country code is not known.
`impossible_length`	The number has too many or too few digits.
`too_long_input`	The input is longer than 64 characters.
`not_in_plan`	The area code or exchange is not in the numbering plan.
`service_code`	The area code or exchange is a service code, like 911 or 411. A service code cannot make calls.
`fictional`	The number is in the 555-0100 to 555-0199 range. This range is for fiction and examples.
`unallocated`	The area code and exchange are not assigned to a carrier.

The input field shows your input. CallerAPI cuts it at 64 characters.

Webhook

What you see	Cause
No events at all	No status changed. Webhooks send only `number.flagged` and `number.cleared`. Send `GET /api/did-monitoring/v1/numbers` to see all results.
No event for a number that became `clean`	The number was not `flagged` before the check, or it went from `flagged` to `unknown` before `clean`.
The same event two times	Delivery is at least one time. Use `id` to find duplicates.
Events out of order	Retries can change the order. Use `data.checked_at`.
Signature does not match	You used the parsed JSON instead of the raw body, you did not use the full secret with `whsec_`, or you used the old secret more than 24 hours after a rotation.
`active` is `false`	CallerAPI turned off the webhook after 50 failed attempts in a row, or after 3 days of failures. Fix the endpoint and save the URL again.
Save returns `400`	The URL is not https, the port is not 443 or 8443, or the host resolves to a private address.

Checks

What you see	Cause
Numbers stay `pending`	The first pass is running, at about 80 numbers a minute. Or the account has no credits.
`state` is `paused`	The account has no credits, or the schedule uses more credits than the plan includes. See the Billing and limits page.
`state` is `off`	`enabled` is `false`. Send `PUT /api/did-monitoring/v1/schedule` with `"enabled": true`.
Status is `unknown`	The check did not finish. The next pass checks the number again. The check used 1 credit.

HTTP endpoints#

Error messages#

Invalid numbers#

Webhook#

Checks#

HTTP endpoints

Error messages

Invalid numbers

Webhook

Checks