Errors - Doodocs People

The class of an error is set by the HTTP status, and the specific cause is carried by the string code field in the response body. Branch on code for programmatic handling — the message text is for humans and may change.

{
  "code": "DEVELOPER.SCOPE_INSUFFICIENT",
  "message": "the API key is missing the required scope: employees:read"
}

Status codes

HTTP	Meaning
400	Bad request (unknown parameter, filter, or token)
401	Key is missing, invalid, revoked, or expired
403	Key lacks a scope, or the feature is not enabled
404	Resource not found (or not accessible to your key)
429	Rate limit exceeded
500	Internal server error

Common codes

`code`	When it happens
`INTEGRATION.API_KEY_INVALID`	Key not accepted: missing, revoked, expired, or unknown
`DEVELOPER.SCOPE_INSUFFICIENT`	The key lacks a scope the endpoint requires
`DEVELOPER.INVALID_EXPAND`	An unknown name was passed in `expand`
`DEVELOPER.INVALID_STATUS`	An unknown value was passed in `status`
`DEVELOPER.INVALID_PAGE_TOKEN`	`page_token` is corrupt or does not match the filters
`EMPLOYEE_NOT_FOUND`	The employee does not exist or is not accessible to the key
`FEATURE_FLAG.NOT_AVAILABLE`	The Developer API is not enabled for the tenant

Non-distinguishability

So the API cannot be used as an oracle, “does not exist,” “no access,” and “draft/deleted” all return the same 404 EMPLOYEE_NOT_FOUND for single resources. The response code cannot tell you whether an employee hidden from you exists.

The API is in preview. Some transcoder errors (for example a typo in a query parameter name) may currently come back as 500; folding every error into a single JSON envelope with the correct status is in progress.