Error Handling

The Netchex External API uses standard HTTP status codes and returns errors in the RFC 9457 Problem Details format (see the Glossary for a plain-language summary).

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 explains 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.

Your API key is valid but lacks permission for the requested operation, or for the specific company/records you asked for. This isn't universal — some endpoints treat an inaccessible resource as 403 (the v1 pay-rates endpoint, and the v3 shifts endpoints for an out-of-scope company), others as 404 or a silently filtered empty result (see 404 below). Check the specific endpoint's own docs for which applies.

404 Not Found

The requested resource doesn't exist, or (on many, but not all, endpoints) your key doesn't have access to it — see 403 above for the endpoints that return 403 for the access case instead.

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.