Errors | Kernsignal API docs

Errors

Every non-2xx response has the same JSON shape.

{
  "error": {
    "type": "invalid_request_error",
    "code": "file_too_large",
    "message": "synthetic_file exceeds 50 MB",
    "param": "synthetic_file"
  }
}

type says what kind of problem it is, code is a stable identifier to branch on, message is for people, param names the offending field or is null.

Types

type	HTTP	Meaning
`invalid_request_error`	400	The request is malformed or not allowed in the current state. Fix it; retrying does not help.
`authentication_error`	401	The API key is missing, malformed or revoked.
`permission_error`	403	The key is valid but may not do this.
`not_found_error`	404	No such resource, or it belongs to another account.
`rate_limit_error`	429	Too many requests. Wait for the `Retry-After` header, then retry.
`api_error`	500	Something failed on our side. Retry with backoff; use an `Idempotency-Key` when creating audits.

Codes you may meet

code	type	Meaning
`file_too_large`	invalid_request_error	An uploaded file is over the size limit (50 MB per file).
`invalid_json`	invalid_request_error	The request body is not a JSON object.
`missing_parameter`	invalid_request_error	A required field is absent. `param` names it.
`audit_not_found`	not_found_error	No audit with that id in your account.
`audit_not_finished`	invalid_request_error	The audit has not succeeded, so it cannot be verified.
`audit_not_verifiable`	invalid_request_error	The audit succeeded but lacks the recorded input hashes or result needed for a record.
`verification_requires_human_evidence`	invalid_request_error	The audit had no `human_file`, or no question was scored against human answers, so no verification record or badge is issued. Submit the audit again with a human file.
`verification_not_found`	not_found_error	No verification with that id, or none exists yet for that audit.
`verification_revoked`	invalid_request_error	A revoked record cannot be edited.
`live_key_required`	permission_error	A `ks_test_` key tried to delete a live audit.
`invalid_display_name`	invalid_request_error	`display_name` must be printable text of at most 80 characters, or null.
`invalid_reason`	invalid_request_error	`reason` must be 1 to 200 printable characters.
`invalid_description`	invalid_request_error	`description` must be a string of at most 200 characters.
`unsafe_url`	invalid_request_error	The webhook URL is not https, uses an IP address or credentials, or resolves to a non-public address.
`invalid_events`	invalid_request_error	Unknown event name in `events`.
`too_many_endpoints`	invalid_request_error	The account already has 10 webhook endpoints.
`webhook_endpoint_not_found`	not_found_error	No such webhook endpoint in your account.
`missing_api_key`	authentication_error	No `Authorization: Bearer` header was sent.
`invalid_api_key`	authentication_error	The API key is malformed or unknown.
`revoked_api_key`	authentication_error	The API key has been revoked.
`route_not_found`	not_found_error	No such endpoint, or the method is not allowed on it.
`invalid_parameter`	invalid_request_error	A field has the wrong type or value. `param` names it.
`unknown_parameter`	invalid_request_error	The request has a field this endpoint does not accept.
`invalid_config`	invalid_request_error	`config` is not a valid JSON object or contains an invalid value (for example `exclude` that is not an array of column names).
`invalid_multipart`	invalid_request_error	The multipart body could not be parsed.
`request_too_large`	invalid_request_error	The whole request body is over the limit (two files of 50 MB plus 1 MB), or a JSON body is over 64 KB.
`unsupported_file_type`	invalid_request_error	The file extension is not one of the accepted types.
`empty_file`	invalid_request_error	An uploaded file is empty.
`invalid_file_content`	invalid_request_error	The file content does not match its type.
`invalid_idempotency_key`	invalid_request_error	`Idempotency-Key` must be 1 to 255 printable characters.
`idempotency_key_reused`	invalid_request_error	The `Idempotency-Key` was already used with different parameters or files.
`audit_not_ready`	invalid_request_error	Reports exist only for succeeded audits.
`queue_full`	rate_limit_error	Too many audits are waiting. Retry in a minute.
`internal_error`	api_error	Something failed on our side. Retry with backoff.
`verification_not_configured`	api_error	The server has no signing key configured. This is our fault; email hello@kernsignal.ai.

Branch on code and treat unknown codes by their type: new codes are added over time.