Error reference

When a request fails, Dockt returns a JSON response that describes the error and identifies its type. These responses use the Problem Details standard with Content-Type: application/problem+json.

Error shape

An error response contains these fields:

{
  "type": "https://docs.dockt.com/errors/invalid-request",
  "title": "Bad request",
  "status": 400,
  "detail": "The supplied cursor is invalid.",
  "instance": "req_example1042",
  "errors": {
    "issues": [
      {
        "path": ["body", "inputs", 3, "value"],
        "message": "Expected a two-letter country code."
      }
    ]
  }
}

Use type as the stable machine-readable error code. Use detail and optional errors.issues to explain the specific request failure. instance is the Dockt request ID when available.

Don’t branch application logic on title or detail; those fields are written for people and can become more specific.

HTTP behavior

A 401 response includes WWW-Authenticate. A 429 response includes Retry-After in seconds. Every API response includes x-request-id; log it and include it when contacting hello@dockt.com.

Error types

Error type	Typical status	Action
Account user conflict	409	Preserve an active owner or resolve membership state.
Conflict	409	Resolve the duplicate or incompatible resource state.
Forbidden	403	Use a compatible scope and permission.
Forbidden scope	403	Select a scope available to the session.
Idempotency conflict	409	Retry the same operation unchanged or use a new key for new work.
Internal error	500	Retry safely and retain the request ID.
Authentication state error	500	Retry authentication and retain the request ID.
Invalid account user	400	Correct the account user or invitation input.
Invalid API credential	400 or 401	Correct credential input or authentication.
Invalid Assessment context	400	Correct the field codes and value types in inputs.
Invalid document upload	400	Send one supported non-empty file within the size limit.
Invalid reference	422	Use a referenced resource valid in the current scope.
Invalid request	400	Correct the request syntax or cursor.
Invalid session scope	409	Select a valid session scope again.
Missing authentication	401	Send a valid bearer token or browser session.
Not found	404	Check the ID and authenticated scope.
Operation unavailable	Varies	Use a documented public operation.
Rate limit exceeded	429	Wait for Retry-After before retrying.
Processing temporarily unavailable	409	Retry the idempotent request later.
Scope context required	409	Select an Account or Workspace in the session.
Validation failed	422	Correct every structured validation issue.
Notification destination inactive	409	Activate the destination before sending a test.
Workspace provisioning required	409	Complete Workspace provisioning before using configuration-dependent operations.