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
  }
}

The Support Code

It is structured so that the category is immediately apparent when read:

STP-DMS-{HTTP-Status}-{Short code}-{Start of request identifier}

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 records.

Retry Behavior

Each code carries one of two recommendations:

For more details, see Idempotency and Retries.

The 401 is the one exception. If the token is missing, expired, or the signature is invalid, the API responds with a bare 401 without an error envelope — meaning no code, no supportCode, and no request identifier. The rejection happens before error handling even takes effect. An integration should therefore never expect a response body for a 401; the status code alone is the signal, and the appropriate action is always the same: obtain a new token.

Authentication and Authorization

Request Validation

Idempotency

Limits and Quotas

Platform and Remote System Errors

Internal Errors

Some errors trigger a security or operational alert internally at STP. Their internal designations are intentionally not exposed outside the platform; externally, they always appear as IMPORT_FAILED — a code from the table above, with the retry recommendation listed there.

For a partner application, this changes nothing: handle the code you receive according to the table above. If such an error recurs, the support code will help take it 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 rule is the HTTP status:

If the code is known, its recommendation from the tables above takes precedence over this fallback rule. This is why INTEGRITY_FAILED carries 🔁 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