Errors

Every error has a stable code. Branch on that, never on the wording.

Errors are returned as problem+json with an extra code field.

{
  "type": "https://novpn.fr/docs/errors#quota_exceeded",
  "title": "Monthly quota exceeded",
  "status": 429,
  "code": "quota_exceeded",
  "detail": "You used every request included in your plan for this billing period.",
  "request_id": "01JXQ..."
}

The code is part of the published contract and will not be renamed. The title and detail are prose and may be reworded, so do not match on them. The type field links straight to the section on this page that describes the error.

What an error costs you

A refusal is always free: a rejected key, a rate limit and an exhausted quota never cost you anything, on any plan. On a paid plan the same is true of a failed lookup, including the ones that are our fault, so you are not charged for an outage or a timeout. On the free plan a failed lookup counts against your quota.

Reference

batch_too_large 400

Batch too large. A batch carries at most 100 addresses, and never more than your plan's per-minute rate, since it spends one of those per address. Split it and send the parts.

invalid_batch 400

Invalid batch. Send a JSON body of the form {"ips": ["203.0.113.7"]} with at least one address.

invalid_ip 400

Invalid IP address. The path segment is not a valid IPv4 or IPv6 address.

invalid_key 401

Invalid API key. No active key matches that value.

key_revoked 401

API key revoked. This key was regenerated or revoked. Copy the current one from your dashboard.

missing_credentials 401

Missing credentials. Send your key as 'Authorization: Bearer nv_live_...' or in the X-API-Key header.

account_suspended 403

Account suspended. This account is suspended. Contact support.

ip_not_allowed 403

Source address not allowed. This key is restricted to an IP allowlist that excludes your address.

ip_not_found 404

Address not in the database. The address is valid but absent from the detection database, so there is nothing to report about it — no score, and no network or country either. A scan has been queued, so retry shortly. This response does not count against your quota.

quota_exceeded 429

Monthly quota exceeded. You used every request included in your plan for this billing period.

rate_limited 429

Too many requests. You exceeded the per-minute request rate for your plan.

internal_error 500

Internal error. Something went wrong on our side.

upstream_error 502

Detection service error. The detection service returned an error. This is not your fault.

upstream_timeout 504

Detection service timeout. The detection service did not answer in time. Retry shortly.

Reporting a problem

Every response carries an X-Request-Id header and a request_id field. Include it when you contact support. With it we can find the exact request in our logs; without it we are guessing.