Errors and troubleshooting

Something didn't work? Find the message you got in this page: each error comes with what it means and how to fix it.

Quick diagnosis

What you see	What it means	How to fix it
HTTP 401 Unauthorized access.	Icypeas doesn't recognise your key.	Copy the key again from the API page, make sure API access is on, and send it alone in Authorization (no Bearer).
HTTP 429 You have exceeded the max number of requests per minute.	You're sending requests too fast.	Wait a few seconds, then retry. Slow down, or switch to bulk search and webhooks. See rate limits.
HTTP 200 with "success": false and validationErrors	Your request reached Icypeas but a field is missing or wrong.	Read the field and type of each error and fix your body. See below.
UnpaidSubscriptionError	A payment is pending on your subscription.	Update your payment method in the billing page.
Status INSUFFICIENT_FUNDS	You don't have enough credits.	Get more credits.
Status BAD_INPUT	The search couldn't run with the data given.	Check the name and the company/domain of that row.
Status stays IN_PROGRESS	The search isn't finished.	Wait a few more seconds and read the result again.
SearchNotFoundError	The id or file you asked for doesn't exist.	Use the exact _id / file returned when you started the search.
Your tool says invalid JSON or unexpected token	The body isn't valid JSON.	Check quotes (use " not ' or “), commas and brackets. Paste it in a JSON validator.
Error on Content-Type / empty body received	The Content-Type header is missing.	Add Content-Type: application/json.

Always check success

Validation errors come back with HTTP status 200, not 400. Don't rely on the HTTP code alone: check that success is true.

Validation errors

When the body doesn't match what an endpoint expects, the API answers:

{
  "success": false,
  "validationErrors": [
    {
      "expected": "string",
      "type": "required",
      "field": "domainOrCompany",
      "message": "validation_required"
    }
  ]
}

Each entry tells you exactly what's wrong:

Key	Meaning	Example
field	The field in error. Nested fields use dots.	domainOrCompany, custom.webhookUrl
type	What kind of problem.	required
expected	What the API wanted.	string
actual	What it received (may be absent).	undefined
message	A stable code you can test in your code.	validation_required

Here, the fix is to add domainOrCompany to the body.

All validation error types

type	message	What's wrong	How to fix it
required	validation_required	The field is missing, null or undefined.	Add the field. Check its spelling and case (firstname, not firstName).
string	validation_string	The field must be text.	Wrap the value in quotes: "123".
stringEmpty	validation_string_empty	The field is an empty string.	Fill it, or remove it if it's optional.
stringEnum	validation_string_enum	The value isn't one of the allowed values.	Use one of the values listed in the endpoint reference, e.g. email-search.
email	validation_email	Not a valid email address.	Check for typos and spaces.
url	validation_url	Not a valid URL.	Use a full URL, starting with https://.
number	validation_number	The field must be a number.	Remove the quotes: 50, not "50".
numberMin / numberMax	validation_number_min / validation_number_max	The number is too small or too big.	Respect the limits of the endpoint (e.g. limit ≤ 100).
boolean	validation_boolean	Must be true or false.	Remove the quotes: true, not "true".
array	validation_array	The field must be a list [ ].	Wrap values in brackets.
arrayEmpty	validation_array_empty	The list is empty.	Add at least one item.
arrayMin / arrayMax	validation_array_min / validation_array_max	Too few or too many items.	A bulk search accepts up to 5,000 rows, a bulk scrape up to 50.
arrayLength	validation_array_length	A row doesn't have the right number of items.	An email-search row has 3 items: first name, last name, company.
arrayEnum	validation_array_enum	A list contains a value that isn't allowed.	Check the allowed values.
FirstLastMandatoryDiscoveryError	first_last_mandatory_discovery_error	Both first name and last name are empty.	Give at least one of them.
ExternalIdsArrayShouldMatchDataArrayError	external_ids_array_should_match_data_array_error	custom.externalIds and data don't have the same length.	Give exactly one id per row.
ModeOrIdShouldBeUsedError	mode_or_id_should_be_used_error	Reading results needs either mode or id.	Send {"id": "…"} or {"mode": "single"}.
SearchNotFoundError	search_not_found_error	The search or file doesn't exist.	Check the id.
FilePropertyError / InvalidFileError	file_property_error / invalid_file_error	The bulk file is invalid.	Check the file id you sent.
UnpaidSubscriptionError	unpaid_subscription_error	A payment is pending.	Update your payment method.

HTTP errors

401 Unauthorized

{
  "message": "Unauthorized access.",
  "error": "UnauthorizedAccessError",
  "status": 401,
  "code": "unauthorized_access_error"
}

Your API key is missing, wrong, or API access is turned off. See Authentication.

429 Too many requests

{
  "message": "You have exceeded the max number of requests per minute.",
  "error": "RateLimitExceededError",
  "status": 429,
  "code": "rate_limit_exceeded_error"
}

Wait, then retry with a growing delay (for example 2 s, 4 s, 8 s). See Rate limits.

Still stuck?

Email support@icypeas.com with the endpoint, the body you sent (without your API key) and the response you got. See Support.