API Errors - Tidyhire API

Error Format

All errors return a consistent JSON body:

{
  "success": false,
  "message": "Description of what went wrong"
}

Validation errors additionally include a top-level errors array with per-field details:

{
  "success": false,
  "message": "Validation error: Candidate's phone must be in E.164 format (e.g. +917873476062)",
  "errors": [
    { "path": "candidates[0].phone", "message": "Candidate's phone must be in E.164 format (e.g. +917873476062)" }
  ]
}

Field labels in errors[].message reflect the payload: a single-entry list reads Candidate's phone, while multiple entries read 1st candidate's phone, 2nd candidate's phone, and so on. The path stays machine-readable.

Status Codes

Code	Meaning	Common Causes
`400`	Bad Request	Malformed request, `schedule_at` in the past, job/project not found or not eligible
`401`	Unauthorized	Missing or invalid `x-tidyhire-api-key` header
`422`	Validation Error	One or more fields failed validation — see `errors`
`429`	Rate Limit Exceeded	Too many requests — see Rate Limits
`500`	Internal Server Error	Unexpected error on our side

The message field is safe to display to users. Write your error handling against success and the status code, not against message text — messages may change.