---
title: "Errors"
url: "https://lookvalid.com/docs/errors.md"
canonical_url: "https://lookvalid.com/docs/errors"
last_updated: "2026-10-20"
type: "reference"
summary: "Every LookValid error code with its HTTP status, whether it is retryable and how to fix it."
related: ["https://lookvalid.com/docs/rate-limits.md"]
---

# Errors

Every LookValid error code with its HTTP status, whether it is retryable and how to fix it.

Every error response is JSON with one envelope. Branch on `code`, never on the message text, which can change. Nothing is charged for a request that returns an error.

```json
{
  "error": {
    "code": "invalid_input",
    "message": "Field \"ip\" is invalid: ...",
    "fix": "Correct the field named in the message and resend. ...",
    "docs_url": "/docs/errors#invalid_input",
    "retryable": false,
    "request_id": "req_..."
  }
}
```

| Field | Meaning |
| --- | --- |
| `code` | Stable machine-readable code. One of the codes below. |
| `message` | What went wrong for this request. |
| `fix` | What to do next. |
| `docs_url` | Link to the section of this page for the code. |
| `retryable` | Whether sending the same request again can succeed. |
| `request_id` | Quote this when you contact support. It matches the `X-Request-Id` header. |

Quote the `request_id` when you write to [hello@lookvalid.com](mailto:hello@lookvalid.com).

## unauthorized

- **HTTP status:** 401
- **Retryable:** no
- **Meaning:** The API key is missing, malformed, revoked or unknown.
- **Fix:** Send a valid key in the Authorization header as "Bearer <key>". If the key was revoked, create a new one and retry.
- **Details:** [unauthorized error page](https://lookvalid.com/docs/errors/unauthorized.md) with the likely cause and a curl example

## forbidden

- **HTTP status:** 403
- **Retryable:** no
- **Meaning:** This API key is not allowed to make this request.
- **Fix:** Use a key from an account that has access to this product, or ask the account owner to grant access.
- **Details:** [forbidden error page](https://lookvalid.com/docs/errors/forbidden.md) with the likely cause and a curl example

## insufficient_credits

- **HTTP status:** 402
- **Retryable:** no
- **Meaning:** The account does not have enough credits for this lookup.
- **Fix:** Add credits to the account, then retry. Nothing was charged for this request.
- **Details:** [insufficient_credits error page](https://lookvalid.com/docs/errors/insufficient_credits.md) with the likely cause and a curl example

## rate_limited

- **HTTP status:** 429
- **Retryable:** yes
- **Meaning:** Too many requests for this API key.
- **Fix:** Wait the number of seconds in the Retry-After header, then retry. Spread requests out to stay under the X-RateLimit-Limit value.
- **Details:** [rate_limited error page](https://lookvalid.com/docs/errors/rate_limited.md) with the likely cause and a curl example

## invalid_input

- **HTTP status:** 400
- **Retryable:** no
- **Meaning:** The request input is invalid.
- **Fix:** Correct the field named in the message and resend. Each product input schema is in the OpenAPI document. Nothing was charged.
- **Details:** [invalid_input error page](https://lookvalid.com/docs/errors/invalid_input.md) with the likely cause and a curl example

## unknown_product

- **HTTP status:** 404
- **Retryable:** no
- **Meaning:** No product exists at this path.
- **Fix:** Check the product id in the URL against the product list in the OpenAPI document or llms.txt.
- **Details:** [unknown_product error page](https://lookvalid.com/docs/errors/unknown_product.md) with the likely cause and a curl example

## method_not_allowed

- **HTTP status:** 405
- **Retryable:** no
- **Meaning:** This endpoint does not accept that HTTP method.
- **Fix:** Use the method named in the Allow response header (lookup endpoints and /v1/mcp accept POST).
- **Details:** [method_not_allowed error page](https://lookvalid.com/docs/errors/method_not_allowed.md) with the likely cause and a curl example

## payload_too_large

- **HTTP status:** 413
- **Retryable:** no
- **Meaning:** The request body is too large.
- **Fix:** Send one lookup input per request and keep the JSON body small. Split large lists into separate requests.
- **Details:** [payload_too_large error page](https://lookvalid.com/docs/errors/payload_too_large.md) with the likely cause and a curl example

## provider_unavailable

- **HTTP status:** 503
- **Retryable:** yes (unless the response says `retryable: false`)
- **Meaning:** The data source for this product is unavailable right now.
- **Fix:** If retryable is true, retry later with exponential backoff. If it is false, this product is not configured on this server and retrying will not help. Nothing was charged.
- **Details:** [provider_unavailable error page](https://lookvalid.com/docs/errors/provider_unavailable.md) with the likely cause and a curl example

## internal_error

- **HTTP status:** 500
- **Retryable:** yes
- **Meaning:** An unexpected error occurred.
- **Fix:** Retry once after a short wait. If it fails again, report the request_id to support. Nothing was charged.
- **Details:** [internal_error error page](https://lookvalid.com/docs/errors/internal_error.md) with the likely cause and a curl example

## not_found

- **HTTP status:** 404
- **Retryable:** no
- **Meaning:** Nothing exists at this address.
- **Fix:** Check the path and any ids in it against the API reference, then retry.
- **Details:** [not_found error page](https://lookvalid.com/docs/errors/not_found.md) with the likely cause and a curl example

## conflict

- **HTTP status:** 409
- **Retryable:** no
- **Meaning:** The request conflicts with the current state of the resource.
- **Fix:** Fetch the resource again, check its current state, then resend if the change still applies.
- **Details:** [conflict error page](https://lookvalid.com/docs/errors/conflict.md) with the likely cause and a curl example

## signature_invalid

- **HTTP status:** 400
- **Retryable:** no
- **Meaning:** The request signature is missing or does not match.
- **Fix:** Sign the exact raw request body with the signing secret this server was given and send the signature header.
- **Details:** [signature_invalid error page](https://lookvalid.com/docs/errors/signature_invalid.md) with the likely cause and a curl example

## plan_limit

- **HTTP status:** 402
- **Retryable:** no
- **Meaning:** The current plan does not allow this.
- **Fix:** Change to a plan that includes it, or reduce usage to stay within the plan, then retry.
- **Details:** [plan_limit error page](https://lookvalid.com/docs/errors/plan_limit.md) with the likely cause and a curl example

## subscription_required

- **HTTP status:** 402
- **Retryable:** no
- **Meaning:** This needs an active subscription.
- **Fix:** Subscribe from the billing page of the dashboard, then retry.
- **Details:** [subscription_required error page](https://lookvalid.com/docs/errors/subscription_required.md) with the likely cause and a curl example

## trial_allowance_exhausted

- **HTTP status:** 402
- **Retryable:** no
- **Meaning:** The trial allowance is used up.
- **Fix:** Nothing was charged. Start your plan from the billing page ("Start my plan now") to keep going; the plan is only charged when you do.
- **Details:** [trial_allowance_exhausted error page](https://lookvalid.com/docs/errors/trial_allowance_exhausted.md) with the likely cause and a curl example

## Related

- [Rate limits](https://lookvalid.com/docs/rate-limits.md)