Request Status Codes

You can tell if your request was successful by checking the status code when receiving an API response. If a response comes back unsuccessful, you can use the error type and error message to figure out what has gone wrong and do some rudimentary debugging (before contacting support). A successful request will be returned with status code 200.

Before reaching out to support with an error, please be aware that 99% of all reported errors are, in fact, user errors. Therefore, please carefully check your code before contacting emailvalidation support.

Status codes

Here is a list of the different categories of status codes returned by the emailvalidation.io API. Use these to understand if a request was successful.

Name
200
Type
Description
A 200 status code indicates a successful response.
Name
201
Type
Description
A 201 status code indicates that a bulk job was created. The response is the queued job.
Name
401
Type
Description
A 401 status code indicates that your request was not authenticated. This happens when no API key is sent at all ({"message": "No API key found in request"}) or when the API key you sent is not a valid emailvalidation.io key. Pass your key as the apikey header or query parameter — see Authentication.
Name
403
Type
Description
A 403 status code indicates that your API key is not allowed to make this request. This happens when the request origin is not on the referrer whitelist configured for your account (it applies to all API keys of your account), when the request comes from an IP address that your account's IP whitelist or blacklist does not allow, or when you use an API key that belongs to a different EverAPI product. When you submit a bulk job, a 403 with the code plan_upgrade_required means that bulk jobs are not enabled for your plan or, with catch_all, that your plan does not include catch-all detection. On a single check, it means that you set catch_all=1 without a plan that includes catch-all detection.
Name
404
Type
Description
A 404 status code indicates that a requested endpoint does not exist. For the bulk endpoints it also means that no job with this job_id belongs to your account (jobs created with sandbox keys are only visible to sandbox keys, live jobs only to live keys), or that the job's results are no longer available.
Name
409
Type
Description
A 409 status code with the code job_not_completed means that you requested the results of a bulk job that is not completed yet, or that failed and has no results. The response carries the job under job; check its status and try again once it is completed.
Name
405
Type
Description
A 405 status code indicates an HTTP method the endpoint does not take (error code method_not_allowed); the Allow header names those it does. A HEAD request answers 405 on every billed endpoint, without running it and without being billed; /v1/status and the other free endpoints answer HEAD like GET.
Name
422
Type
Description
A 422 status code indicates that a validation error has occurred. One or more request parameters are missing or invalid — the errors object in the response body names the affected parameter(s). For a bulk job this includes an empty list, too many rows, a file that is too large or not a CSV or TXT file, a row with more than 500 columns, an email_column that is not in the file, a list that could not be read in time, and a webhook_url that is not an https URL on a public host. See Bulk job errors.
Name
429
Type
Description
A 429 status code indicates that you have hit your rate limit or your monthly limit. For more requests please upgrade your plan. A bulk job that costs more than your quota allows is refused with 429 before it runs; quota.required in the response says how many requests it needs. A validation sent while your account already runs as many as its plan allows at the same time is answered with 429 and the code concurrency_limit_exceeded; send it again after the seconds in Retry-After.
Name
500
Type
Description
A 500 status code indicates an internal server error - let us know: support@emailvalidation.io

Error response body

Error responses are JSON. Every error contains a human-readable message; the other fields depend on the status code. Validation errors (422) carry an info link pointing back to this page and an errors object naming the offending parameter(s). 401, 403, 404, 405, 409 and 429 errors instead carry a machine-readable error object with a stable code, plus suggested next steps under actions — and quota-related 429s additionally include a quota object, as in the example below. Other errors carry the message only, for example a 403 because of your IP whitelist or blacklist, a 500, and the 502 or 504 our gateway returns when validation does not answer in time. A 429 of the free plan's minute rate limit also has a Retry-After header with the seconds until the next minute starts.

Example 422 response

{
    "message": "Validation error",
    "errors": {
        "email": [
            "The email field is required."
        ]
    },
    "info": "For more information, see documentation: https://emailvalidation.io/docs/status-codes/#_422"
}

Example 429 response

{
    "message": "You used all your monthly requests. Please upgrade your plan at https://app.emailvalidation.io/upgrade",
    "error": {
        "code": "quota_exceeded",
        "message": "You used all your monthly requests. Please upgrade your plan at https://app.emailvalidation.io/upgrade"
    },
    "quota": {
        "limit": 100,
        "used": 100,
        "remaining": 0,
        "resets_at": "2026-09-01T00:00:00+00:00"
    },
    "actions": {
        "upgrade": "https://app.emailvalidation.io/upgrade?utm_source=api_error&utm_campaign=quota_exceeded",
        "docs": "https://emailvalidation.io/docs/openapi.yaml"
    }
}

Stable error.code values include missing_api_key, invalid_api_key, key_not_allowed_for_product, referrer_not_allowed, quota_exceeded, grace_quota_exceeded, overage_quota_exceeded, rate_limit_exceeded, not_found, forbidden, plan_upgrade_required and job_not_completed. Bulk job errors found while reading a submitted list or checking its webhook_url carry invalid_parameters (see below); other 422 validation errors have no error.code.

Bulk job errors

The bulk endpoints answer with these errors in addition to the ones above. Errors found while reading a submitted list or checking its webhook_url carry error.code invalid_parameters next to the usual errors object.

Status	`error.code`	When
`403`	`plan_upgrade_required`	Bulk jobs are not enabled for your plan, or you set `catch_all` without a plan that includes catch-all detection.
`403`	`forbidden`	The API key does not belong to an emailvalidation.io account.
`404`	`not_found`	No job with this `job_id` belongs to your account (for this kind of key), or its results are no longer available.
`409`	`job_not_completed`	You requested the results of a job that is not completed yet, or that failed.
`422`	`invalid_parameters` or none	The list or a parameter is invalid; `errors` names the field (`emails`, `emails.<n>` for the item at index `n`, `file`, `email_column`, `webhook_url`, `catch_all`, `limit`, `before` or `format`).
`429`	`quota_exceeded` or `grace_quota_exceeded`	The job costs more than your quota allows; `quota.required` is its cost. Nothing was stored or billed.

Example 422 response (bulk job)

{
    "message": "Validation error",
    "error": {
        "code": "invalid_parameters",
        "message": "Validation error"
    },
    "actions": {
        "sign_up": "https://app.emailvalidation.io/register?utm_source=api_error&utm_campaign=invalid_parameters",
        "docs": "https://emailvalidation.io/docs/openapi.yaml"
    },
    "errors": {
        "webhook_url": [
            "The webhook_url must be an https URL."
        ]
    },
    "info": "For more information, see documentation: https://emailvalidation.io/docs/status-codes#_422"
}

Example 429 response (bulk job)

{
    "message": "This request needs 1200 requests, but your quota only allows 994 more. Please upgrade your plan at https://app.emailvalidation.io/upgrade",
    "error": {
        "code": "quota_exceeded",
        "message": "This request needs 1200 requests, but your quota only allows 994 more. Please upgrade your plan at https://app.emailvalidation.io/upgrade"
    },
    "quota": {
        "limit": 1000,
        "used": 5,
        "remaining": 995,
        "resets_at": "2026-11-01T00:00:00+00:00",
        "required": 1200
    },
    "actions": {
        "upgrade": "https://app.emailvalidation.io/upgrade?utm_source=api_error&utm_campaign=quota_exceeded",
        "docs": "https://emailvalidation.io/docs/openapi.yaml"
    }
}