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.
401	Unauthorized	Authentication is missing or invalid.
403	Forbidden	The caller is not permitted to access this resource.
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.
429	Too Many Requests	The rate limit has been exceeded; back off and retry.
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" }
  ]
}