Read an error response
API v2 application errors use anerror object with code, message, and requestId. For example, this synthetic response represents a rejected request:
x-request-id response header also identifies the request. Save it with the HTTP status, method, and path. When asking for help, include the request ID and time of the request. Remove credentials and personal data from anything you share.
Fix validation errors
Schema validation errors useVALIDATION_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:
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
For credential setup, see Authentication. For budget headers and a retry example, see Rate limits. OAuth’s authorization and token endpoints use their own OAuth error responses.
Retry safely
Retry read operations, including employee searches, after a temporary network failure or server error using bounded exponential backoff with jitter. On429, 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 returns409 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 with CURRENT. Creating the same email doesn’t restore the employee.