Errors

Conventional HTTP response codes indicate the success or failure of an API request:

• 2xx codes indicate success.

• 4xx codes indicate a failure due to the information provided, such as an omitted required parameter or insufficient permissions.

• 5xx codes indicate an error on Workiva’s servers.

Code	Meaning	Description
400	Bad Request	The request was unacceptable, often due to a missing or invalid parameter, or an attempt to change a read-only field such as an issue’s status. For POST /issues/export, an invalid filter, an updatedAt window that is too long or starts in the future, an unsupported format, or more than 50,000 matching issues when the request arrives (if the count passes 50,000 later, the operation fails instead, with the reason in details).
401	Unauthorized	Authentication is missing or invalid.
403	Forbidden	The caller is not permitted to access this resource. For issues and action tasks, an id that does not exist, one the caller cannot read, and an action task that belongs to a different issue all return 403, so the response does not reveal which ids exist.
404	Not Found	The requested resource was not found.
409	Conflict	The request conflicts with the current state of the target resource — for example, a scope operation attempted on a project that does not support control scoping, or an action task update or state change that is not allowed from the task’s current state, such as a PATCH on an implemented or cancelled action task, or one whose assigneeStatus is completed or cancelled (see Updating Resources).
429	Too Many Requests	The rate limit has been exceeded; back off and retry. POST /issues/export also returns 429 with a Retry-After header when you already have a different export in flight (see Limits).
500	Internal Server Error	Something went wrong on Workiva’s end.
503	Service Unavailable	The server can’t handle the request due to a temporary overload or scheduled maintenance.
504	Gateway Timeout	The request did not complete within a timely manner.

Error Object

Name	Type	Required	Description
message	string	true	A human-readable representation of the error.
code	string	false	A stable, machine-readable identifier for the error.
target	string	false	The target of the error — a /-prefixed JSON Pointer for a body field, or a $-prefixed query parameter.
details	[object]	false	Per-item errors (used by batch endpoints).
details.code	string	false	Machine-readable code for the specific item error.
details.message	string	true	Human-readable message for the specific item error.
details.target	string	false	Target of the specific item error, e.g. /data/2.

Error Example

{
  "message": "The $filter value could not be parsed.",
  "code": "invalidFilter",
  "target": "$filter"
}

For a batch request, per-id failures are reported in details:

{
  "message": "One or more requested ids could not be returned.",
  "code": "invalidRequest",
  "details": [
    { "code": "notFound", "message": "No resource with this id was found.", "target": "/data/2" }
  ]
}

A 400 for a body field names the field as a JSON Pointer in target. For example, a malformed id in a batch request is reported at its position in data:

{
  "message": "Invalid id",
  "code": "invalidRequest",
  "details": [
    {
      "message": "Invalid id",
      "code": "invalidRequest",
      "target": "/data/0"
    }
  ]
}

For issues and action tasks, an id that does not exist and an id the caller cannot read are indistinguishable by design: both return 403 with code permissionDenied. This includes an action task requested under an issue it does not belong to, and a batch retrieval that includes any id that is missing or unreadable (the request returns no partial results).

A failed export is reported on its operation: GET /operations/{operationId} returns the failed status with the reason in details. See Operations.