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

# Errors

> Diagnose API failures with status codes, validation details, and request IDs.

## Read an error response

API v2 application errors use an `error` object with `code`, `message`, and `requestId`. For example, this synthetic response represents a rejected request:

```json theme={null}
{
  "error": {
    "code": "BAD_REQUEST",
    "message": "The request was invalid",
    "requestId": "019a1234-5678-7000-8000-000000000002"
  }
}
```

The `x-request-id` response header also identifies the request. Save it with the HTTP status, method, and path. When [asking for help](mailto:support@gowindmill.com), include the request ID and time of the request. Remove credentials and personal data from anything you share.

### Fix validation errors

Schema validation errors use `VALIDATION_ERROR` and add `error.details`, an array of objects with a `path` array and a `message`. A path identifies the invalid field, including array indexes when applicable. For example:

```json theme={null}
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "requestId": "019a1234-5678-7000-8000-000000000003",
    "details": [
      {
        "path": ["page"],
        "message": "Too small: expected number to be >=1"
      }
    ]
  }
}
```

Check the operation's schema for supported fields, types, and limits. Some domain-level `400` responses still have a generic message. Use the request ID when the response doesn't explain enough to resolve the problem. Treat messages as diagnostic text rather than values to parse for control flow.

## Handle common statuses

| Status | Next step |
| - | - |
| `400 Bad Request` | Check JSON, field names, types, limits, and operation prerequisites. Correct the request before retrying. |
| `401 Unauthorized` | Supply a valid bearer credential. Check expiration and revocation; replace the key or refresh the OAuth token as appropriate. |
| `403 Forbidden` | Confirm the credential's workspace, API-key access mode, and the user's current workspace and resource permissions. |
| `404 Not Found` | Check the workspace and resource IDs. Confirm the resource belongs to that workspace and is accessible to the caller. |
| `409 Conflict` | Resolve the existing record or conflicting state before sending another write. |
| `429 Too Many Requests` | Wait for `Retry-After` and reduce your request pace. The error code is `RATE_LIMITED`. |

For credential setup, see [Authentication](https://help.gowindmill.com/api-reference/authentication.md). For budget headers and a retry example, see [Rate limits](https://help.gowindmill.com/api-reference/rate-limits.md). OAuth's authorization and token endpoints use their own [OAuth error responses](https://help.gowindmill.com/api-reference/oauth.md#handle-oauth-errors).

## Retry safely

Retry read operations, including [employee searches](https://help.gowindmill.com/api-reference/employees/search-employee-profiles.md), after a temporary network failure or server error using bounded exponential backoff with jitter. On `429`, respect `Retry-After` before retrying. Stop after a bounded number of attempts and retain the request IDs.

Review each write operation before retrying. A timeout doesn't tell you whether a write committed. Windmill has no `Idempotency-Key` support, and employee creation isn't an upsert.

### Resolve duplicate employees

[Create an employee](https://help.gowindmill.com/api-reference/employees/create-an-employee.md) returns `409` for an existing current **or former** employee. If a create times out, search for the employee before deciding whether to create again. Don't interpret a duplicate conflict as proof that your earlier request succeeded with every intended field.

To rehire an archived employee, use [Set an employee's employment status](https://help.gowindmill.com/api-reference/employees/set-an-employees-employment-status.md) with `CURRENT`. Creating the same email doesn't restore the employee.


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