type, title, status, and detail field, which makes automated error handling straightforward for both human developers and AI agents.
type field is "about:blank" for most errors. Validation errors, entity report errors (see Entity report errors) and withdrawn trust badge calls (see Trust Badge Unavailable) use a type URI that links to their entry on this page.Status Code Reference
Error Response Format
Standard Error
All non-2xx responses return RFC 7807 problem details:Validation Error (422)
Field-level validation errors return adetail array instead of a string. A missing field, an invalid value and a malformed JSON body all answer this way. Field names are sanitized, so internal paths are not exposed:
Invalid value. A few rules that Limitguard checks itself carry their own message.
400 Bad Request
Unsubstituted path parameter
Unsubstituted path parameter
:name placeholder, such as :entity_id, copied from a discovery listing instead of a real identifier.example field shows the shape of a call; it is not a guaranteed-valid identifier.Invalid tier on key creation or upgrade
Invalid tier on key creation or upgrade
POST /v1/keys/create accepts only the free and sandbox tiers, and POST /v1/keys/upgrade/{tier} accepts only a tier you can upgrade to. detail says which.Fix: Create a free or sandbox key, then use POST /v1/keys/upgrade/{tier} with an x402 payment to upgrade.401 Unauthorized
Missing X-API-Key header
Missing X-API-Key header
X-API-Key header, and no payment header (PAYMENT-SIGNATURE or X-PAYMENT) was provided either.X-API-Key: lg_live_xxxxxxxxxxxxxxxxxxxx to every request. Free endpoints (health, key creation, well-known routes) never require authentication.Revoked or expired key
Revoked or expired key
POST /v1/keys/create. Keys are returned once: if lost, create a new one.Test key in production
Test key in production
lg_test_ was sent to the production API, which refuses it: 401 Test keys not accepted in production.Fix: For mock data use a sandbox key (lg_sandbox_..., free from POST /v1/keys/create with "tier": "sandbox"); for real data use an lg_live_ key. There is no sandbox header: X-Limitguard-Mode is ignored.402 Payment Required
HTTP 402 is a protocol response, not just an error. Limitguard implements the x402 V2 micropayment protocol. When you receive a 402, the response body is not an RFC 7807 error: it is a payment requirements object.PAYMENT-SIGNATURE header (or the V1 X-PAYMENT header).Payment Requirements Response
accepts entry also repeats resource, description and mimeType, and a third entry offers the settled-transfer scheme. The field reference is on the x402 Protocol page.
x402 Payment Flow
Receive 402
accepts array. Choose an entry whose network (a CAIP-2 chain ID) your agent can pay on.Check the amount
amount field uses 6 decimal places: 290000 is $0.29 USDC, the x402 agent price of the fresh tier of POST /v1/entity/check (an API key is debited the account price instead). Pay the amount the 402 quotes, and verify your wallet has sufficient balance before signing.Build EIP-3009 signature (EVM) or SPL transfer (Solana)
TransferWithAuthorization to the entry’s payTo, with a unique nonce and a validBefore no more than ten minutes ahead (the quote’s maxTimeoutSeconds is 600). See the x402 Protocol guide for full code examples.Retry with the payment header
PAYMENT-SIGNATURE (x402 V2) or X-PAYMENT (V1). Retry the exact same endpoint and body.Common 402 Sub-Cases
Insufficient payment amount
Insufficient payment amount
amount in your payment object is less than the minimum required for the endpoint and quality tier.amount value from the 402 response exactly. If using a non-default X-Response-Quality tier, the required amount changes: cached requires less. See the pricing table for per-endpoint amounts.Expired payment signature (validBefore exceeded)
Expired payment signature (validBefore exceeded)
validBefore timestamp in the EIP-3009 signature has passed (errorCode: expired_payment). The quote’s maxTimeoutSeconds is 600, so sign a validBefore no more than ten minutes ahead.Fix: Rebuild the payment with a fresh timestamp. Do not cache signatures for reuse: build a new one per request.Nonce replay detected
Nonce replay detected
Invalid payment signature
Invalid payment signature
sender field matches the wallet that signed the transaction. Verify the EIP-712 domain parameters match exactly: name: "USD Coin", version: "2", chainId as integer, verifyingContract as the USDC contract address.Unsupported chain
Unsupported chain
network (or chainId) in your payment is not one the quote listed in accepts (errorCode: unsupported_network).Fix: Pay one of the networks in the 402’s accepts array. The production API quotes eip155:8453 (Base Mainnet) and solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp (Solana Mainnet).x402 error codes
A 402 that rejects a payment carrieserrorCode in its body beside error; the facilitator endpoints /x402/verify and /x402/settle return the same values as invalidReason. This table is generated from the API’s X402ErrorCode enum.
403 Forbidden
Entity report with a sandbox key
Entity report with a sandbox key
POST /v1/reports/entity (and the MCP get_compliance_report tool) was called with a sandbox key. Reports are built only from real checks.lg_live_ key or pay per call with x402.Operator route
Operator route
/v1/admin/*). Customer keys carry the least-privileged role, so the API answers 403 with Insufficient role or Insufficient permissions.Fix: None needed on your side: these routes are not part of the customer API.Watchlist without an API key
Watchlist without an API key
/v1/watchlist) belong to an API key’s own tenant. A call that reached them without a key-bound tenant, for example one paid only by x402, is answered 403 Tenant context required.Fix: Call the watchlist routes with an API key.Entity report errors
POST /v1/reports/entity and GET /v1/reports/{report_id} answer errors as RFC 7807 problem details whose type links to the entries below. Each body also carries instance (the request path) and errorCode.
404 Not Found
Webhook not found
Webhook not found
DELETE /v1/webhooks/{webhook_id} or test call was made with an unknown webhook_id, or with the ID of a webhook another API key registered.Fix: Use GET /v1/webhooks to list all registered webhooks and confirm the correct webhook_id.Unknown endpoint path
Unknown endpoint path
/v1/entity/checks instead of /v1/entity/check) or a missing version prefix.Fix: All API endpoints are under /v1/. Refer to the API Reference for the exact path of each endpoint.No History
GET /v1/reputation/history/{entity_hash} answers 404 for an entity that has never been scored, so there is no trend to return. The payment is not settled, so nothing is charged.
POST /v1/entity/check for the entity first. Every check is recorded and becomes a point on the trend.
410 Gone
Trust Badge Unavailable
GET /v1/badge/{entity_id}, GET /v1/badge/{entity_id}.json and GET /v1/verify/{entity_id} were withdrawn on 8 Oct 2026. They showed a demo score that was not based on any check. They take no API key and charge nothing. The SVG route answers with this JSON body, not an image.
instance echoes the path you called, for example a /v1/badge/ path. All three routes give the same 410 body.
What to do: Remove the badge or link. To check a company, use POST /v1/entity/check.
Compliance Report Unavailable
GET /v1/compliance/report/{entity_id} is withdrawn. It returned the same EU AI Act briefing for every entity, so it was not the per-entity assessment it was priced as. It answers 410 with errorCode compliance_report_unavailable and charges nothing.
What to do: For an EU AI Act readiness score from inputs you supply, use GET /v1/compliance/readiness/{entity_id}. For a per-entity report built from a real check, use POST /v1/reports/entity; when it is offered, alternatives in the 410 body names it.
422 Unprocessable Entity
422 errors occur when the request body is missing a required field, a value is invalid, or the body is not valid JSON. For field validation thedetail field is an array of field-level errors; a few checks made after validation (such as the webhook URL check) return a single string detail instead. Nothing is charged.
field is the character position of the parse error, such as "19". Send Content-Type: application/json and build the body with json.dumps() in Python or JSON.stringify() in JavaScript rather than by hand.
Common Validation Errors
Invalid country code
Invalid country code
country is not a valid ISO 3166-1 alpha-2 code, or uses the alpha-3 format.Fix: Use two-letter uppercase codes: NL, BE, DE, FR, US. Not NLD, Netherlands, or lowercase nl.entity_name too short or too long
entity_name too short or too long
entity_name is fewer than 2 characters or more than 255 characters.Fix: Pass the legal entity name as registered. Single-character values and very long strings are rejected.Invalid KVK number format
Invalid KVK number format
kvk_number contains non-numeric characters or is not exactly 8 digits.Fix: KVK numbers are always 8 digits: "12345678". Do not include spaces, dashes, or the KVK: prefix.Invalid IBAN format
Invalid IBAN format
iban fails structural validation (country prefix, check digits, or length for the given country).Fix: Pass a complete IBAN including country code and check digits: "NL91ABNA0417164300". Strip spaces before sending.Invalid VAT number format
Invalid VAT number format
vat_number does not match the expected format for the given country prefix.Fix: Include the country prefix: "NL123456789B01", "BE0123456789". Format rules vary by country: see the European Commission VIES guidelines for country-specific formats.Invalid wallet address
Invalid wallet address
wallet_address is not a valid EVM (0x…, 42 chars) or Solana (base58, 32-44 chars) address.Fix: Validate the address client-side before sending. EVM addresses must be checksummed or all-lowercase hex. Solana addresses must be valid base58.Invalid domain format
Invalid domain format
domain contains a protocol prefix, path, or query string instead of a bare hostname.Fix: Send the bare domain only: "acmecorp.nl", not "https://acmecorp.nl/about?lang=en".Invalid webhook event type
Invalid webhook event type
events array in POST /v1/webhooks contains an unrecognized event name.Fix: Use event types from the list in the Webhooks guide: sanctions.match.new, trust.score.changed, trust.level.downgrade, certificate.expired or identifier.change.new. There is no * wildcard. Only sanctions.match.new and identifier.change.new are sent today; delivered_events in the registration response lists which of yours are live.Invalid webhook URL
Invalid webhook URL
url in POST /v1/webhooks is not https://, its host does not resolve, or it resolves to a private, loopback, link-local, reserved or cloud-metadata address. This error carries a plain string detail instead of the field array above:detail values: "URL must use HTTPS" and "Cannot resolve hostname '<host>': ...".Fix: Use a public https:// URL whose host resolves in public DNS.429 Too Many Requests
Limitguard enforces three independent limits per key: a per-minute limit, a rolling 24-hour limit and a calendar-month cap. A verified x402 payer has a per-minute limit only.Rate Limit Response
Retry-After Header
Every 429 response includes aRetry-After header with the number of seconds to wait:
Rate Limits by Tier
Daily Limit Reached
When a key hits its rolling 24-hour limit, thedetail names it:
Retry-After, top up to a higher tier for a higher limit, or pay per call with x402, which has no daily cap. The daily caps on keys are abuse limits, not a usage allowance you buy.
Monthly Cap Reached
Each key also has a calendar-month cap equal to its tier’s number in the table above. It resets at 00:00 UTC on the 1st. The 429 carriesRetry-After set to the seconds until then, and no X-RateLimit-* headers:
detail quotes the price and names the keyless x402 call. A call you pay for with x402 counts toward the cap but is not refused by it.
500 Internal Server Error
- Note the
Request IDfrom thedetailfield. - Retry with exponential backoff: most 500s are transient.
- If the error persists for more than 5 minutes, check api.limitguard.ai/health for service status.
- Report persistent 500s to support@limitguard.ai with the Request ID.
503 Service Unavailable
- Check
Retry-Afterheader if present. - Subscribe to status updates at api.limitguard.ai/health.
- For x402 users: the circuit breaker fallback (cached wallet verification) handles most dependency failures transparently. A 503 indicates a more severe outage.
Request validation errors
Validation Error
HTTP422, errorCode validation_error.
What happened: The request body does not fit the endpoint. detail lists every field that failed with what is wrong with it; a rule about two fields names both. Nothing was charged.
What to do: Fix the fields detail names and send the request again.
Lead Verify errors
Lead Verify Not Available
HTTP404, errorCode lead_verify_not_available. The MCP tool answers status rejected with the same sentence as error and lead_verify_not_available as code.
What happened: Lead Verify is switched off on this server. Nothing was charged.
What to do: Try again later.
Lead Verify Not Available In Sandbox
HTTP403, errorCode lead_verify_not_available_in_sandbox. The MCP tool answers status rejected with the same sentence as error and lead_verify_not_available_in_sandbox as code.
What happened: Lead Verify only runs on the live company registers, so it does not work with a sandbox key. Use a live key. Nothing was charged.
What to do: Use a live key.
Lead Verify Invalid
HTTP422, errorCode lead_verify_invalid. The MCP tool answers status rejected with the same sentence as error and lead_verify_invalid as code.
What happened: The company_number cannot be checked: it is not a KVK or KBO number, or it belongs to the other country. Nothing was charged.
What to do: Enter an 8-digit KVK number (NL) or a 10-digit KBO number (BE); put a VAT number in vat_number. Check that country matches the number.
Lead Verify Unavailable
HTTP503, errorCode lead_verify_unavailable. The MCP tool answers status rejected with the same sentence as error and lead_verify_unavailable as code.
What happened: The company register could not be reached. Nothing was charged.
What to do: Try again in a few minutes.
Agent check errors
Agent Check Not Available
HTTP404, errorCode agent_check_not_available. The MCP tool answers status rejected with the same sentence as error and agent_check_not_available as code.
What happened: The agent check is not available yet. Nothing was charged.
What to do: The agent check is switched off for now. Try again later.
Agent Check Not Available In Sandbox
HTTP403, errorCode agent_check_not_available_in_sandbox. The MCP tool answers status rejected with the same sentence as error and agent_check_not_available_in_sandbox as code.
What happened: The agent check only runs on live sources, so it does not work with a sandbox key. Use a live key. Nothing was charged.
What to do: Use a live key.
Agent Check Unavailable
HTTP503, errorCode agent_check_unavailable. The MCP tool answers status rejected with the same sentence as error and agent_check_unavailable as code.
What happened: None of the wallet checks could be completed. Nothing was charged.
What to do: Try again in a few minutes.
Cached result errors
Not Cached
HTTP404, errorCode not_cached.
What happened: No cached result for this entity; no data source was called. Nothing was charged.
What to do: Send the request again with X-Response-Quality: fresh for a full check.
Error Handling Patterns
Recommended Client Logic
x402 Auto-Payment Handler
For AI agents that need to handle 402 responses automatically:Debugging Checklist
Getting 401 even with a valid key?
Getting 401 even with a valid key?
- Confirm the header name is exactly
X-API-Key(capital X, capital A, capital K) - Confirm the key value starts with
lg_live_orlg_sandbox_(lg_test_keys are refused in production) - Check for leading/trailing whitespace in the header value
- Verify the key has not been revoked: create a new one at
POST /v1/keys/create
Getting 422 but my JSON looks correct?
Getting 422 but my JSON looks correct?
- Check that
countryis exactly 2 uppercase characters:"NL"not"nl"or"Netherlands" - Check that
entity_nameis at least 2 characters - For
kvk_number: digits only, exactly 8 characters, as a string:"12345678"not12345678 - For
iban: strip all spaces before sending - The
detailarray in the response will list every failing field: read all of them before retrying
Getting 403 but my key is valid?
Getting 403 but my key is valid?
- Run
GET /v1/usage/summarywith your key to see your current tier - Check the 403 causes above: sandbox keys get no entity reports, operator routes are not part of the customer API, and the watchlist needs a key-bound tenant
x402 payment keeps returning 402?
x402 payment keeps returning 402?
- Confirm
validBeforeis at least 60 seconds in the future and within the quote’smaxTimeoutSeconds(600, ten minutes) - Confirm
chainIdin the payment payload exactly matches thenetworkof theacceptsentry you pay - Confirm
recipientis that entry’spayTo: do not substitute your own address - Confirm
amountmatches or exceeds theamountthe 402 quoted - Generate a new random nonce for every attempt: do not reuse
- Confirm the USDC contract address is that entry’s
asset(each network has its own)
Intermittent 500 errors on entity checks?
Intermittent 500 errors on entity checks?
- 500 on entity checks is usually a transient timeout in a data source (e.g., KVK API slow response)
- Retry up to 3 times with exponential backoff: 1s, 2s, 4s
- If the error persists, try
X-Response-Quality: cachedto bypass live source queries - Include the
Request IDfrom the error body when contacting support