Errors

The ywork API uses conventional HTTP status codes to indicate the result of a request. Codes in the 2xx range indicate success, 4xx codes indicate a problem with the request, and 5xx codes indicate a problem on ywork’s side.

Error format

Errors return a JSON body with a single error object:

{
  "error": {
    "type": "invalid_request_error",
    "code": "validation_failed",
    "message": "The 'name' field is required.",
    "request_id": "req_7c3f5a9e12"
  }
}

Field	Description
type	A broad category for the error (see below).
code	A short, machine-readable code for the specific error.
message	A human-readable description, suitable for logging.
request_id	A unique identifier for the request. Include it in support requests.

Error types

type	Meaning
authentication_error	The API key is missing or invalid.
invalid_request_error	The request was malformed or failed validation.
rate_limit_error	Too many requests — see Rate limits.
api_error	An unexpected error occurred on ywork’s side.

Status codes

Status	Meaning
200	OK — the request succeeded.
201	Created — a new resource was created.
204	No Content — the request succeeded with no response body.
401	Unauthorized — no valid API key was provided.
404	Not Found — the resource does not exist.
422	Unprocessable Entity — the request body failed validation.
429	Too Many Requests — the rate limit was exceeded.
5xx	Server error — something went wrong on ywork’s side.

Always inspect the HTTP status code first, then the error.code for programmatic handling.