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.
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.