> ## Documentation Index
> Fetch the complete documentation index at: https://developer.karmacheck.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Status codes and errors

> HTTP status codes used by the KarmaCheck API and the structure of error responses.

The KarmaCheck API uses conventional HTTP response codes to indicate the success or failure of an API request. In general, a 2*xx* status code indicates success, a 4*xx* status code indicates an error based on the information provided, and a 5*xx* 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 4*xx* 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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```json theme={null}
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:

```json theme={null}
{
  "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:

```json theme={null}
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:

```json theme={null}
{
  "message": "Case has already started",
  "error": "Unprocessable Entity",
  "statusCode": 422
}
```