Errors

An error means the request itself could not be handled: a missing key, a bad URL, a rate limit, a fault on our side. A site that is blocked or down is not an error: that is a successful response with an outcome.

Errors use the problem details format of RFC 9457, with Content-Type: application/problem+json:

HTTP/1.1 422 Unprocessable Content
Content-Type: application/problem+json

{
  "type": "https://linkspect.com/problems/invalid-url",
  "title": "Invalid URL",
  "status": 422,
  "detail": "The URL must use a host name, not an IP address.",
  "instance": "/v1/checks"
}

type is stable: switch on it in your code. title and detail are for people and may change. New types can be added within /v1, so keep a fallback by status code.

Types

All types start with https://linkspect.com/problems/.

Type	Status	When
`unauthorized`	401	No API key, or the key is wrong.
`forbidden`	403	The key may not make this request.
`not-found`	404	No such resource for this key. Another key's check is also "not found".
`invalid-parameter`	400	A query or path parameter is wrong: `limit` outside 1–200, a `cursor` the server did not give you, a malformed date-time, an ID of the wrong shape (`GET /v1/checks/chk_nope` is 400, not 404), a country code that is not two capital letters.
`invalid-request`	422	The body is not JSON or does not fit the schema: empty `targets`, an unknown `check_type` or `profile`, a `content` check without `content.expect`, an unknown or repeated browser.
`invalid-url`	422	The URL is not accepted: not `http`/`https`, an IP address instead of a name, a user name or password in it, a single-label name, or a name in `.local`, `.internal` or `.arpa`.
`invalid-target`	422	A target is wrong, for example an unknown country code or connection type.
`unknown-operator`	422	The operator is not in that country's catalog (see `GET /v1/geos/{country}`).
`idempotency-key-reuse`	422	The `Idempotency-Key` was already used with a different body. See Idempotency.
`rate-limited`	429	The key's rate limit is used up. Wait `Retry-After` seconds. See Rate limits.
`internal`	500	Something failed on our side. Retrying is safe with an `Idempotency-Key`.

What to retry

429: yes, after Retry-After.
500 and network errors: yes, with backoff. For POST /v1/checks, send an Idempotency-Key so a retry cannot create a second check.
400, 401, 403, 404, 422: no. The same request will fail the same way.