Error Handling

The Netchex External API uses standard HTTP status codes and returns errors in the RFC 9457 Problem Details format.

Error Response Format

All error responses have a consistent JSON body:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
  "title": "Not Found",
  "status": 404,
  "detail": "The requested employee was not found or is not accessible.",
  "instance": "/employees/99999"
}

Field	Description
`type`	A URI identifying the problem type (usually an RFC link)
`title`	Short human-readable summary of the problem type
`status`	The HTTP status code
`detail`	Human-readable explanation specific to this occurrence
`instance`	The request URI that caused the error (optional)

Validation Errors

For 400 Bad Request errors caused by invalid input, the response includes a field-level errors map:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "Bad Request",
  "status": 400,
  "detail": "start-date is required.",
  "errors": {
    "startDate": ["start-date is required."],
    "endDate": ["end-date must be greater than or equal to start-date."]
  }
}

HTTP Status Codes

200 OK

Request succeeded. The response body contains the requested data.

400 Bad Request

The request was malformed or contained invalid parameters. Common causes:

Missing a required query parameter (e.g. start-date, end-date)
A date is not in YYYY-MM-DD format
end-date is before start-date
Providing more than one mutually exclusive filter (e.g. both company-ids and employee-ids for time punches)
Providing neither of two required alternatives
Array length exceeds the documented maximum (e.g. more than 100 organization-ids)
page-size outside the allowed range

Fix: Read the detail field — it will explain exactly what was wrong.

401 Unauthorized

Your API key is missing, malformed, or not recognized.

{
  "title": "Unauthorized",
  "status": 401
}

Fix: Check that the Authorization header is set to ApiKey YOUR_KEY with no extra spaces or characters.

403 Forbidden

403 may rarely appear in older API versions (v1/v2). v3 does not return 403 — inaccessible resources return 404 or empty results instead.

Your API key is valid but lacks permission for the requested operation. Most access control in v1/v2 silently returns empty results rather than this status, so encountering a 403 is uncommon.

404 Not Found

The requested resource does not exist, or your key does not have access to it. In v3, inaccessible resources always return 404 rather than 403.

For endpoints like GET /time-punches and GET /direct-entry-earnings, 404 can also mean no records matched your filters (distinct from an empty page).

500 Internal Server Error

An unexpected error occurred on the server. These are not caused by your request and are typically transient.

{
  "title": "Internal Server Error",
  "status": 500,
  "detail": "An unexpected error occurred. Please try again."
}

Fix: Retry with exponential backoff. If the error persists, contact support.

Error Handling

On this page