Errors

The HTTP status sets the class of an error, and a string code carries the exact cause. That code arrives in the X-Error-Reason header and is repeated in the response body. The body is a standard google.rpc.Status, so its code field is a number (the gRPC code), not a string.

HTTP/1.1 403 Forbidden
Content-Type: application/json
X-Error-Reason: DEVELOPER.SCOPE_INSUFFICIENT

{
  "code": 7,
  "message": "the API key is missing the required scope: employees:read",
  "details": [
    {
      "@type": "type.googleapis.com/google.rpc.ErrorInfo",
      "reason": "DEVELOPER_SCOPE_INSUFFICIENT",
      "domain": "doodocs.people",
      "metadata": { "code": "DEVELOPER.SCOPE_INSUFFICIENT" }
    }
  ]
}

Branch on the X-Error-Reason header for programmatic handling. If headers are not available to you, the same code sits in details[].metadata.code, and details[].reason holds it with dots replaced by underscores. The message text is for humans and may change, so never match on it.

Do not branch on the numeric code in the body: that is the gRPC code, not the Doodocs error code. The 7 above means PermissionDenied, not “insufficient scope”.

For “resource not found” errors, details carries a second entry, google.rpc.ResourceInfo, with resourceType and resourceName.

Status codes

HTTP	Meaning
400	Bad request (unknown parameter, filter, or token)
401	Key is missing, invalid, or revoked
403	Key lacks a scope, or the feature is not enabled
404	Resource not found (or not accessible to your key)
409	Conflict: an `Idempotency-Key` already used in Ingest
429	Rate limit exceeded
500	Internal server error

Error codes

Key and access

Code	HTTP	When it happens
`INTEGRATION.API_KEY_INVALID`	401	Key not accepted: missing, revoked, or unknown
`DEVELOPER.SCOPE_INSUFFICIENT`	403	The key lacks a scope the endpoint requires
`FEATURE_FLAG.NOT_AVAILABLE`	403	The Developer API is not enabled for the tenant
`INTEGRATION.API_KEY_SCOPE_INVALID`	400	An unknown scope was passed when creating a key

Lists and parameters

Code	HTTP	When it happens
`DEVELOPER.INVALID_PAGE_TOKEN`	400	`page_token` is corrupt or does not match the filters
`DEVELOPER.INVALID_EXPAND`	400	An unknown name was passed in `expand`
`DEVELOPER.INVALID_STATUS`	400	An unknown value was passed in `status`
`DEVELOPER.INVALID_ARGUMENT`	400	The request body fails validation (for example `template_values` does not match the schema)

Employees

Code	HTTP	When it happens
`EMPLOYEE_NOT_FOUND`	404	The employee does not exist or is not accessible to the key

Documents

Code	HTTP	When it happens
`DOCUMENT_NOT_FOUND`	404	The document does not exist or is not accessible to the key
`DOCUMENT_TEMPLATE_NOT_FOUND`	404	The template does not exist, is inactive, or has no published version
`DOCUMENT_FILE_NOT_FOUND`	404	The document has no file of the requested `file_type`
`DOCUMENT_INITIATOR_NOT_FOUND`	404	The key owner is not an employee of this tenant
`DEVELOPER.INVALID_SIGN_METHOD`	400	`sign_method` is missing or unsupported

Files

Code	HTTP	When it happens
`FILE_NOT_FOUND`	404	The file does not exist or is not accessible to the key
`FILE.INVALID_CONTENT_TYPE`	400	The content type is not supported
`FILE.INVALID_SIZE`	400	The size is outside the allowed range
`FILE.PENDING_LIMIT_EXCEEDED`	400	Too many unconfirmed uploads
`FILE.NOT_UPLOADED`	400	`_confirm` was called before the upload reached storage
`FILE.SIZE_MISMATCH`	400	The uploaded file exceeds the declared `size_bytes`
`FILE.ALREADY_LINKED`	400	The file is already linked to another entity
`FILE.IN_USE`	400	The file is in use and cannot be changed
`FILE.NOT_FILE_OWNER`	403	The file was uploaded by a different key owner

Webhooks

Code	HTTP	When it happens
`WEBHOOK_NOT_FOUND`	404	The subscription does not exist
`DEVELOPER.WEBHOOK_URL_INVALID`	400	The URL is not `https` or points at a private address
`DEVELOPER.WEBHOOK_EVENT_INVALID`	400	An unknown event type was passed
`DEVELOPER.WEBHOOK_EVENT_TYPES_REQUIRED`	400	No event type was passed
`DEVELOPER.WEBHOOK_ROTATION_IN_PROGRESS`	409	A previous secret is still inside its window
`WEBHOOK_DELIVERY_NOT_FOUND`	404	No delivery with that id
`DEVELOPER.WEBHOOK_DELIVERY_NOT_REDELIVERABLE`	400	The subscription is disabled, so a repeat would fail

Ingest

Code	HTTP	When it happens
`INTEGRATION.IDEMPOTENCY_REQUIRED`	400	The `Idempotency-Key` header was not sent
`INTEGRATION.IDEMPOTENCY_REQUIRED`	409	A load with this `Idempotency-Key` was already accepted
`DEVELOPER.IDEMPOTENCY_KEY_CONFLICT`	409	The key was already used with a different request body
`DEVELOPER.IDEMPOTENCY_IN_PROGRESS`	409	The first call with this key is still running

Why 404 instead of 403

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

Preview limitations

A rate-limit error (429) arrives with no X-Error-Reason and an empty details. Identify it by the status, and take the pause from the Retry-After header.
A typo in a query parameter name is handled by the transcoder before it reaches the API and returns 500 with an unknown field in field path message. An unknown parameter value still returns a proper 400.

Overview

Endpoints

Status codes

Error codes

Key and access

Lists and parameters

Employees

Documents

Files

Webhooks

Ingest

Why 404 instead of 403

Preview limitations

​Status codes

​Error codes

​Key and access

​Lists and parameters

​Employees

​Documents

​Files

​Webhooks

​Ingest

​Why 404 instead of 403

​Preview limitations

Status codes

Error codes

Key and access

Lists and parameters

Employees

Documents

Files

Webhooks

Ingest

Why 404 instead of 403

Preview limitations