Documents Partner API Error Codes

Every error response from the API carries a stable error code. This is the part of the response that an integration should program against — not the message text.

Structure of an Error Response

{
  "error": {
    "code": "CONNECTOR_OFFLINE",
    "message": "The customer's connector is not currently connected; retry.",
    "correlationId": "9f3a2b7c4d1e5081",
    "supportCode": "STP-DMS-502-CONN-OFFLINE-9f3a2b7c",
    "details": null,
    "retryAfter": null
  }
}

Every error response generated by the API itself follows this structure. A small number of rejections occur before the API's own error handling kicks in — in those cases, the status code is returned without a response body. Details are provided in the box under Retry Behavior.

The Support Code

It is structured so that the category is immediately recognizable at a glance:

STP-DMS-{HTTP-Status}-{short-code}-{start of correlation ID}

Example: STP-DMS-502-CONN-OFFLINE-9f3a2b7c

A partner application should pass this through to the end user. This gives STP Support a single identifier to locate the request in logs and trace recordings.

Retry Behavior

Every code carries one of two recommendations:

For full details, see Idempotency and Retries.

Two cases are returned without the standard error wrapper. Both are rejected before the API's own error handling ever runs:

• 401 — the token is missing, has expired, or has an invalid signature. The same bare 401 is also returned for URLs that don't exist: without a valid token, it's impossible for an external caller to determine whether an endpoint exists at all. The correct response is always the same: obtain a new token.
• 400 or 404 for a malformed URL — if the URL contains a character that isn't allowed there, or a segment such as .., the request is rejected before it even reaches the API. The exact response (status code and whether a response body is included) is not part of the versioned contract for this API in these edge cases — unlike every other error in this table, an integration should not expect a specific code, format, or status code here. In either case, check the URL being called. Standard percent-encoding is not affected — an invalid percent-encoded value is handled normally and returns VALIDATION_FAILED with the standard error wrapper.

An integration must not expect a response body in the 401 case; the status code alone conveys the information.

Authentication and Authorization

Request Validation

Idempotency

Limits and Quotas

Platform and Connector Outages

Internal Errors

Some errors trigger an internal security or operations alert at STP. Their internal designations are intentionally not exposed outside the platform; externally, IMPORT_FAILED is always returned instead — a code from the table above, with the retry recommendation listed there.

For a partner application, this changes nothing: it handles the code it receives according to the table above. If such an error recurs, the support code will help take things further.

Handling Unknown Codes

New codes may be added within a major version. An integration must therefore be able to handle an unknown code without crashing. The reliable fallback is the HTTP status:

If the code is known, its recommendation from the tables above takes precedence — not this fallback rule. That is why INTEGRITY_FAILED carries a 🔁 even though it is a 422: the error occurs in transit and clears on the next attempt. The fallback rule only applies to codes an integration does not yet recognize.

For more details, see Versioning and Deprecation.

Further Reading

• Idempotency and Retries
• Endpoint Overview