Errors

Errors use one envelope and a stable code. Errors are never billed.

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "This lookup needs 1 credit; 0 left.",
    "docs_url": "https://validationcheck.net/docs/errors#insufficient_credits",
    "request_id": "req_7757…"
  }
}

Code	HTTP	Retry?
INVALID_REQUEST	400	No
INVALID_INPUT	400	No
MISSING_FIELD	400	No
UNAUTHORIZED	401	No
INSUFFICIENT_CREDITS	402	After topping up
FORBIDDEN_SCOPE	403	No
ACCOUNT_SUSPENDED	403	No; contact support
NOT_FOUND	404	No
IDEMPOTENCY_CONFLICT	409	Yes
INPUT_LIMIT_EXCEEDED	413	No
RATE_LIMITED	429	Yes, after Retry-After seconds
INTERNAL_ERROR	500	Yes, with backoff
UPSTREAM_UNAVAILABLE	503	Yes, with backoff
MAINTENANCE	503	Yes, after Retry-After seconds

INVALID_REQUEST

The body isn’t valid JSON, or a field has the wrong type. The message names the field.

INVALID_INPUT

The JSON is fine but the value can’t be checked: an email with no @, an IP that isn’t an address, a phone with no digits, a domain without a known suffix.

MISSING_FIELD

A required field is missing, for example email on /v1/email.

UNAUTHORIZED

No key, a malformed key, or a key that’s revoked or expired.

INSUFFICIENT_CREDITS

Your balance can’t cover this check. Nothing is charged. X-Credits-Remaining shows your balance; top up or upgrade in the dashboard.

FORBIDDEN_SCOPE

The key doesn’t have the scope this endpoint needs. See Authentication.

ACCOUNT_SUSPENDED

Your account is suspended, so lookups are refused. The message includes the reason; you can still sign in to the dashboard. Contact support@validationcheck.net.

NOT_FOUND

There’s no endpoint at that method and path.

IDEMPOTENCY_CONFLICT

The Idempotency-Key was already used with a different request, or the first request with it is still running. See Idempotency.

INPUT_LIMIT_EXCEEDED

The request body is larger than 64 KB.

RATE_LIMITED

Too many requests. Wait Retry-After seconds. See Rate limits.

INTERNAL_ERROR

Something failed on our side. It’s logged; retry with backoff.

UPSTREAM_UNAVAILABLE

A data source didn’t respond. Nothing was charged; retry with backoff.

MAINTENANCE

ValidationCheck is briefly down for maintenance. Nothing was charged; retry after the Retry-After header (60 seconds).