Skip to main content

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:
The 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 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:
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

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. 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 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 with CURRENT. Creating the same email doesn’t restore the employee.