> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.jazzhq.ai/api-reference/errors/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.jazzhq.ai/_mcp/server.

# Errors

JazzHQ APIs use standard HTTP status codes to indicate whether a request was successful.

Error responses are returned as JSON and include a machine-readable `message` that can be used to identify the error.

## Error response

```
{
  "message": "VALIDATION_FAILED",
  "status": 400,
  "success": false,
  "errors": [
    {
      "field": "companyName",
      "error": "COMPANY_NAME_MANDATORY"
    }
  ],
  "timestamp": "2026-08-01T09:15:00"
}
```

For validation errors, the `errors` array contains details about the fields that caused the request to fail.

## Error codes

| HTTP status | Code                       | Description                                                           |
| ----------- | -------------------------- | --------------------------------------------------------------------- |
| `400`       | `VALIDATION_FAILED`        | One or more request fields are invalid or missing.                    |
| `400`       | `INVALID_REQUEST`          | The request could not be processed.                                   |
| `400`       | `DUPLICATE_ENTRY`          | The request conflicts with an existing resource.                      |
| `401`       | `API_KEY_MISSING`          | The API key was not provided.                                         |
| `401`       | `INVALID_API_KEY`          | The provided API key is invalid.                                      |
| `401`       | `UNKNOWN_API_NAMESPACE`    | The request path is outside the namespace this key is authorized for. |
| `404`       | `RESOURCE_NOT_FOUND`       | The requested resource could not be found.                            |
| `409`       | `INVALID_STATE_TRANSITION` | The request conflicts with the resource's current state.              |
| `500`       | `INTERNAL_SERVER_ERROR`    | An unexpected error occurred.                                         |

## Examples

### Authentication errors

**`No X-API-KEY header sent`**

```json title="No X-API-KEY header sent"
{
  "success": false,
  "message": "API_KEY_MISSING",
  "data": null,
  "timestamp": "2026-08-01T09:15:00"
}
```

**`Invalid API key`**

```json title="Invalid API key"
{
  "success": false,
  "message": "INVALID_API_KEY",
  "data": null,
  "timestamp": "2026-08-01T09:15:00"
}
```

### Validation errors

**`Required fields are missing`**

```json title="Required fields are missing"
{
  "message": "VALIDATION_FAILED",
  "status": 400,
  "success": false,
  "errors": [
    {
      "field": "companyName",
      "error": "COMPANY_NAME_MANDATORY"
    },
    {
      "field": "contactEmailAddress",
      "error": "CONTACT_EMAIL_MANDATORY"
    }
  ],
  "timestamp": "2026-08-01T09:15:00"
}
```

### State conflicts

Some actions are only valid from certain states. Approving a lead that was already
rejected, or rejecting one that has already been converted into a contact, returns `409`
rather than `400` — the request itself is fine, but the resource has moved on.

**`Approving a lead that was already rejected`**

```json title="Approving a lead that was already rejected"
{
  "message": "INVALID_STATE_TRANSITION",
  "status": 409,
  "success": false,
  "errors": [
    {
      "field": "approvalStatus",
      "error": "A rejected lead cannot be approved."
    }
  ],
  "timestamp": "2026-08-01T09:15:00"
}
```

Retrying a request that already succeeded does **not** produce this error. Archiving an
already-archived lead, re-approving an approved one, or re-rejecting a rejected one all
succeed and change nothing.

### Resource errors

**`Requested resource was not found`**

```json title="Requested resource was not found"
{
  "message": "RESOURCE_NOT_FOUND",
  "status": 404,
  "success": false,
  "errors": [
    {
      "field": "resource",
      "error": "The requested resource was not found."
    }
  ],
  "timestamp": "2026-08-01T09:15:00"
}
```

> **Note**
>
> For validation errors, check the `errors` array for field-level details.

> Error responses and codes returned by the JazzHQ APIs