Errors

The Knock API uses standard HTTP status codes. 2xx means success, 4xx means something about the request needs to change, and 5xx means something went wrong on Knock's side.

Error formatCopy Anchor Link

Errors from the API have a JSON body with three fields:

{
  "errors": ["Enrichment request not found"],
  "code": "external-api.enrichment-request.not-found",
  "metadata": {
    "vendorId": "3f6a2b1c-8d4e-4f5a-9b6c-7d8e9f0a1b2c",
    "enrichRequestId": "7d0f4f1e-2c3b-4a8e-9a51-0e6f3b8c2d14"
  }
}

A few responses are produced before a request reaches the Knock API itself and use a simpler body without a code:

{
  "statusCode": 413,
  "message": "request entity too large"
}

This happens for an oversized body (413), malformed JSON (400), the per-IP rate limit (429), an unknown path (404) and unexpected server errors (500). Handle errors by HTTP status first, then by code when it's present.

Error codesCopy Anchor Link

Other 5xx responses, such as 503 or 504, are temporary too: retry with backoff.

Validation errorsCopy Anchor Link

A 400 validation response lists every problem it found, each prefixed with the path of the field:

{
  "errors": [
    "people.0.email: email must be an email",
    "people.2.firstName: firstName must be shorter than or equal to 320 characters"
  ],
  "code": "validation",
  "metadata": {}
}

Common messages:

One invalid item rejects the whole request, and nothing is submitted or charged. Send the body as JSON with Content-Type: application/json; a body Knock can't read as JSON also gets 400, with the plain {statusCode, message, error} body and no code.

Retrying safelyCopy Anchor Link

Use exponential backoff with jitter for retries, for example 1, 2, 4, 8 and 16 seconds plus a random fraction, and give up after about five attempts. Rate limits has a ready-made retry helper.

Request IDsCopy Anchor Link

Almost every response carries an X-Request-Id header with a unique ID for that request (not 413 or malformed-JSON 400 responses, which are rejected before the request is logged). Log it with your errors and include it when you contact Knock about a specific call: it lets the team find that request quickly.

HTTP/1.1 502 Bad Gateway
Content-Type: application/json; charset=utf-8
X-Request-Id: 0b4c7f9e-1d2a-4e3b-8c5d-6f7a8b9c0d1e