Error Codes

The API uses standard HTTP status codes and returns JSON error responses.

HTTP Status Codes

Code	Meaning	Description
200	OK	Request succeeded
400	Bad Request	Missing or invalid parameters
401	Unauthorized	Missing API key
403	Forbidden	API key is inactive or revoked
404	Not Found	Endpoint does not exist
405	Method Not Allowed	HTTP method not supported for this endpoint
429	Too Many Requests	Rate limit or quota exceeded
500	Internal Server Error	Something went wrong on our end
503	Service Unavailable	Dependent service temporarily unavailable

Error Response Format

All error responses follow a consistent ErrorInfo format:

{
  "requestId": "a1b2c3d4-...",
  "path": "/api/v1/email",
  "code": "MISSING_PARAMETER",
  "message": "Parameter 'address' is required",
  "details": []
}

Field	Type	Description
requestId	string	Correlation ID for tracing (may be null if generated before correlation filter)
path	string	Request URI that triggered the error
code	string	Machine-readable error code (see table below)
message	string	Human-readable description
details	array	Additional field-level errors (empty for most errors)

Error Codes

Code	HTTP Status	Description
UNAUTHORIZED	401	Missing X-Api-Key header
FORBIDDEN	403	Invalid or inactive API key
MISSING_PARAMETER	400	Required parameter not provided
INVALID_FORMAT	400	Parameter value is malformed
VALIDATION_ERROR	400	General validation failure
RESOURCE_NOT_FOUND	404	Endpoint or resource does not exist
METHOD_NOT_ALLOWED	405	HTTP method not supported for this endpoint
RATE_LIMIT_EXCEEDED	429	Per-minute rate limit exceeded
QUOTA_EXCEEDED	429	Monthly quota exhausted
DAILY_QUOTA_EXCEEDED	429	Daily quota exhausted
UPSTREAM_UNAVAILABLE	502	External dependency failed
SERVICE_UNAVAILABLE	503	Service temporarily unavailable
INTERNAL_ERROR	500	Unexpected server error

Common Errors

Missing API Key

curl https://api.iqxlookup.neivi.es/api/v1/email?address=test@example.com

{
  "requestId": null,
  "path": "/api/v1/email",
  "code": "UNAUTHORIZED",
  "message": "Missing X-Api-Key header",
  "details": []
}

Invalid Parameters

curl -H "X-Api-Key: ALk-your-key" \
  "https://api.iqxlookup.neivi.es/api/v1/email"

{
  "requestId": "a1b2c3d4-...",
  "path": "/api/v1/email",
  "code": "MISSING_PARAMETER",
  "message": "Parameter 'address' is required",
  "details": []
}

Rate Limit Exceeded

{
  "requestId": "a1b2c3d4-...",
  "path": "/api/v1/email",
  "code": "RATE_LIMIT_EXCEEDED",
  "message": "Rate limit exceeded. Try again later.",
  "details": []
}