Errors

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.

1{
2  "error": {
3    "code": "invalid_input",
4    "message": "Field \"ip\" is invalid: ...",
5    "fix": "Correct the field named in the message and resend. ...",
6    "docs_url": "/docs/errors#invalid_input",
7    "retryable": false,
8    "request_id": "req_..."
9  }
10}

Quote the request_id when you write to 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 with the likely cause and a curl example