Errors
The LinkinLegal API error body, the full table of HTTP statuses and error codes, what to do with each one, and how to report a problem.
Every failed request returns a JSON body with one error object. The HTTP status tells you the class of the problem. The code tells you the exact problem.
{
"error": {
"type": "invalid_request_error",
"code": "unknown_parameter",
"message": "Unknown parameter: limit.",
"request_id": "2184f0b6-9412-4fb8-81cd-a2b40d585511"
}
}| Field | What it is |
|---|---|
type | The class of the error. Use it to group errors in your logs. |
code | The exact error. Branch your code on this value, never on the message. |
message | A sentence for a human. It can change; do not parse it. |
request_id | The id of this request. Log it. Send it to support. |
Error codes
| HTTP | type | code | Meaning | What to do |
|---|---|---|---|---|
| 400 | invalid_request_error | invalid_request | A field has the wrong value or is missing. The message names the fields. | Fix the request. Do not retry the same body. |
| 400 | invalid_request_error | unknown_parameter | You sent a parameter that does not exist. | Check the spelling against the reference. |
| 400 | invalid_request_error | query_too_short | query holds no token with three or more letters or digits. | Ask the user for more text before you call. |
| 401 | authentication_error | invalid_api_key | The key is missing, malformed, unknown or revoked. | Check the Authorization header and the key in your secret store. |
| 402 | billing_error | plan_required | Your account has no active plan for this API. | Buy the API in the developer console, or renew it. |
| 403 | permission_error | missing_scope | The key does not carry the scope the endpoint needs. | Create a key with the scope sanctions:read. |
| 403 | permission_error | subscription_required | The LinkinLegal app subscription of the account is not active. | Renew the app subscription. See Plans and billing. |
| 403 | permission_error | account_blocked | We blocked the account. | Write to support@linkinlegal.com. Retries do not help. |
| 404 | invalid_request_error | entity_not_found | No entity has this id, in this type. | Check the id and the type parameter. Entities can be removed from the data. |
| 404 | invalid_request_error | not_found | No endpoint has this path. | Check the path and the method. |
| 429 | rate_limit_error | rate_limit_exceeded | You passed the per-minute limit. | Wait, then retry. See Rate limits. |
| 500 | api_error | internal_error | The request failed on our side. | Retry once after a short wait. If it stays, send us the request_id. |
| 503 | api_error | index_unavailable | match only: the match index is not ready. | Retry in a few minutes. See Match. |
Unknown parameters fail
The API is strict about parameters. A parameter it does not know is an error, not something it ignores.
# Wrong: the page size parameter is per_page, not limit.
curl -s -G "https://api.linkinlegal.com/v1/sanctions/search" \
-H "Authorization: Bearer $LINKINLEGAL_API_KEY" \
--data-urlencode "query=Gulina" \
--data-urlencode "limit=5"{
"error": {
"type": "invalid_request_error",
"code": "unknown_parameter",
"message": "Unknown parameter: limit.",
"request_id": "2184f0b6-9412-4fb8-81cd-a2b40d585511"
}
}Why we do this
A misspelt filter that is ignored returns an unfiltered list. The list looks correct, so nobody notices, and you screen against the wrong set. A loud 400 is better than a quiet wrong answer.
Errors inside a batch
POST /sanctions/match/batch is different. A bad item does not fail the call. The call stays 200, and that item gets its own error object under its own key:
{
"responses": {
"cust-1": { "results": [] },
"cust-2": {
"error": {
"code": "invalid_request",
"message": "Invalid request fields: properties."
}
}
}
}Read every key of responses and check for error before you read results. Read Match.
Report a problem
Write to support@linkinlegal.com. Send us:
- The
request_idfrom the error body, or theX-Request-Idheader of the response. - The time of the call, with the time zone.
- The endpoint and the request body or query, without your API key.
With the request_id we find the exact call in our logs. Never send us your API key.
Last updated on
Authentication
Send your LinkinLegal API key in the Authorization header. Key format, scopes, the 20-key limit, revocation and key safety rules.
Rate limits
The LinkinLegal API allows 120 requests per minute per account. Read the rate limit headers, handle a 429 with backoff, and ask for a higher limit.