Status codes and errors

The KarmaCheck API uses conventional HTTP response codes to indicate the success or failure of an API request. In general, a 2xx status code indicates success, a 4xx status code indicates an error based on the information provided, and a 5xx status code indicates an error with KarmaCheck servers.

HTTP status codes

Code	Title	Description
200	OK	The request was successful.
400	Bad Request	The request couldn’t be processed. This might be due to issues in the request body.
403	Forbidden	The user doesn’t have permissions to access the requested resource.
404	Not Found	The resource path doesn’t exist. This might be due to an invalid resource ID that was provided.
409	Conflict	The request conflicts with the resource’s current state.
422	Unprocessable Entity	The request contains data that fails validation rules or business rules.
500	Internal Server Error	A problem occurred on KarmaCheck’s end.

Errors

Errors are returned as JSON-based messages. Most 4xx responses include an error message that briefly explains the error, which can be handled programmatically. The following sections provide examples of different types of error responses.

400 Bad Request

Your request body has one of the following issues:

A required field is missing.
A field contains the wrong format or data type.

For example, you want to find relevant jurisdictions for a county, but didn’t provide the state:

{
  "message": [
    "counties.0.state must be a string"
  ],
  "error": "Bad Request",
  "statusCode": 400
}

403 Forbidden

You don’t have permission to access a specific resource:

{
  "message": "You do not have access to documents for case e074241e-36e8-444b-bf55-bb4dad6d3f3d",
  "error": "Forbidden",
  "statusCode": 403
}

404 Not Found

The resource (for example, a case) associated with the ID provided in the path parameter doesn’t exist:

Invalid case

409 Conflict

A request to create a case includes an email address associated with a candidate who is already the subject of an existing case within the same group:

{
  "httpStatus": "CONFLICT",
  "cases": [
    {
      "existingCaseId": "afe52932-7c0d-4233-93f9-ce6ee3d0bede",
      "existingCaseCrStamp": "2024-05-30T00:02:12.000+00:00",
      "existingCasePackageId": "d04defe1-1ea5-43fc-1832-231a5d23a08b",
      "existingCasePackageName": "Basic Check",
      "existingCaseStatusId": "d894b8a0-937e-46b1-8799-15bad611844f",
      "existingCaseStatus": "Pending",
      "modStamp": "2024-05-31T00:02:17.000+00:00"
    }
  ]
}

To create a new case associated with the same candidate, resend the request with orderOverride in the request body. Depending on the value provided (add or replace), a successful request results in one of the following:

The new case is created in addition to the existing case.
The existing case is archived, and the new case is created.

422 Unprocessable Entity

The request contains data that fails validation. For example, a request to create a case using the PII entry flow is missing required candidate information:

Requested package requires candidate phone number

The request doesn’t align with business logic. For example, you can’t resend the invitation associated with a case if a candidate has already begun the onboarding process:

{
  "message": "Case has already started",
  "error": "Unprocessable Entity",
  "statusCode": 422
}

​HTTP status codes

​Errors

​400 Bad Request

​403 Forbidden

​404 Not Found

​409 Conflict

​422 Unprocessable Entity