> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tidyhire.app/llms.txt
> Use this file to discover all available pages before exploring further.

# API Errors

> Error responses, HTTP status codes, and how to handle them

## Error Format

All errors return a consistent JSON body:

```json theme={null}
{
  "success": false,
  "message": "Description of what went wrong"
}
```

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

```json theme={null}
{
  "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](/api-reference/rate-limit) |
| `500` | Internal Server Error | Unexpected error on our side |

<Info>
  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.
</Info>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.