Errors | JazzHQ AI | Documentation

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

{
  "success": false,
  "message": "API_KEY_MISSING",
  "data": null,
  "timestamp": "2026-08-01T09:15:00"
}

Invalid API key

{
  "success": false,
  "message": "INVALID_API_KEY",
  "data": null,
  "timestamp": "2026-08-01T09:15:00"
}

Validation errors

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

{
  "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

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

For validation errors, check the errors array for field-level details.