API Reference

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 incorrect permissions.
  • 5xx codes indicate an error with Workiva's servers.
CodeMeaningDescription
400Bad RequestThe request was unacceptable, often due to missing a required parameter
401UnauthorizedNo valid API token provided
403ForbiddenThe API token doesn't have permissions to perform the request
404Not FoundThe requested resource doesn't exist
409ConflictThe request conflicts with another request
429Too Many RequestsToo many requests too quickly, recommend backoff
500Internal Server ErrorSomething went wrong on Workiva's end

Two error responses may be returned.

  • An error code of 400 returns a multi-error response.
  • Any other error code returns a single error response.

Single Error Object

NameTypeRequiredDescription
bodystringfalseAdditional details of the error
codeinteger(int32)falseA server-defined error code

Example Single Error

{
  "code": "404",
  "body": "Not found"
}

Multi Error Object

NameTypeRequiredDescription
body[string]falseList containing additional details of the error
codeinteger(int32)falseA server-defined error code

Example Multi Error Response

{
  "code": "400",
  "body": ["Invalid request"]
}