Errors

iplyt API errors return JSON with a human-readable error message and a machine-readable code.

Error object

{
  "error": "no IP provided",
  "code": "MISSING_IP"
}

Some errors include extra fields (for example max on TOO_MANY_IPS).

Lookup errors

Code	HTTP status	Description
`MISSING_IP`	400	No `ip` query parameter
`MISSING_IPS`	400	Empty IP list in POST body
`TOO_MANY_IPS`	400	More than 100 IPs in POST lookup
`INVALID_JSON`	400	POST body not string or string array
`INVALID_REQUEST`	400	Invalid bulk lookup body
`LOOKUP_FAILED`	400 / 404 / 500	Invalid IP, not found, or internal error
`MULTI_LOOKUP_FAILED`	500	Batch lookup processing error
`BULK_LOOKUP_FAILED`	500	Bulk lookup processing error

Global errors

These can be returned on any route:

Code	HTTP status	Description
`NOT_FOUND`	404	Unknown path
`REQUEST_TOO_LARGE`	413	Body larger than 10 MB
`RATE_LIMIT_EXCEEDED`	429	Rate limit exceeded
`CONCURRENCY_LIMIT_EXCEEDED`	503	Server at concurrency cap
`REQUEST_TIMEOUT`	504	Request exceeded timeout

Authentication errors

Invalid, disabled, revoked, or expired API keys return 401 with a descriptive message.

Multi-IP partial failures

For POST /api/v1/lookup with an array of IPs, failed lookups appear in the response array with an error field on each object rather than failing the whole request.

Platform proxy (homepage demo)

The marketing demo at /api/iplyt/lookup is unauthenticated and may return:

Code	Description
`MISSING_IP`	No IP detected and none provided
`INVALID_IP`	Client-side format validation failed
`REQUEST_FAILED`	Internal API unreachable

This endpoint is for demonstration only — not for production integrations.