Troubleshooting and Error Codes

Error response formats

The API currently uses two top-level error response formats. Check the HTTP status first, then handle either format when you parse an error response.

Validation details

Validation may return a 422 Unprocessable Entity response with a detail field. Request schema validation commonly returns an array:

{
  "detail": [
    {
      "loc": ["string", 0],
      "msg": "string",
      "type": "string"
    }
  ]
}

The loc field identifies where validation failed. The msg and type fields describe the issue.

Endpoint-specific validation may return detail as a string instead. Treat the detail value as human-readable context in either form.

LeadX error envelope

Application and runtime errors commonly use the LeadX error envelope:

Field	Description
`success`	Always `false` for errors
`error.code`	High-level classification (e.g., `VALIDATION_ERROR`, `ERROR`)
`error.message`	Human-readable description of what went wrong
`error.field`	The specific input field that failed validation, if applicable
`error.status`	HTTP status code
`error.request_id`	Unique identifier for debugging and support
`error.timestamp`	When the error occurred

Common Error Codes

400 Bad Request

Returned when parameters are malformed or logically invalid.

{
  "success": false,
  "error": {
    "code": "ERROR",
    "message": "modified_date may not be in the future.",
    "status": 400,
    "request_id": "a1e41ec1-64d8-4916-b69d-7082723ece2e",
    "timestamp": "2025-09-16T02:13:11+00:00"
  }
}

401 Unauthorized

Occurs when authentication is missing or incorrect.

Ensure you are using the correct HTTP method (e.g., sending GET instead of POST may trigger 401).
Verify your API key is included in the request headers. See the Authentication section for details on how to obtain an API key.

{
    "success": false,
    "error": {
        "code": "UNAUTHORIZED",
        "message": "Not authenticated",
        "status": 401,
        "request_id": "b4fa29c3-b968-4bc7-bab2-6edb5044e3da",
        "timestamp": "2025-09-16T02:46:24+00:00"
    }
}

404 Not Found

Returned when the requested resource or endpoint does not exist. Check if you entered the full and correct endpoint path.

{
  "detail": "Not Found"
}

422 Unprocessable Entity

Returned when request validation fails. Depending on where validation fails, the response uses either the detail format or the LeadX error envelope documented above.

Common causes:

Invalid JSON body
Empty request body
Supplying fields that are not allowed
Missing required fields

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Field required",
    "field": "email",
    "status": 422,
    "request_id": "xxxx-xxxx",
    "timestamp": "2025-09-13T15:58:47+00:00"
  }
}

500 Internal Server Error

Indicates an unexpected issue on the server side.

If this persists, contact LeadX support and provide the request_id from the error response.

internal server error

Troubleshooting Tips

Use HTTPS

Always start your request URL with https:// (not http://).

Check HTTP Method

Check that you are using the correct HTTP method (GET vs. POST).

Verify Endpoint URL

Remove extra spaces or trailing slashes at the end of the endpoint.

Verify Authentication

Ensure you have a valid and correct API key.

Include Required Parameters

Some endpoints need specific parameters. Ensure you've included all required parameters.

Validate Request Body Format

If the endpoint expects JSON in the body of the request, validate that your request body follows the proper JSON schema. An improper schema will result in a 422 error (i.e., "message": "JSON decode error").