The Partner API uses standard HTTP status codes. 2xx means success; 4xx means the request needs to change before retrying; 5xx means a server-side problem.

​
Status code summary

​
Error details

All errors return a JSON body with a human-readable message. Shape:
When: A required field is missing, a value is the wrong type, or a JSON array field (selectedControlItemIds, selectedControlClusterIds) is malformed.Fix: Check the message for the offending field. Validate the request body against the endpoint schema in the API Reference before retrying.
When: The X-API-Key header is missing, empty, or not a recognized key.Fix: Send a valid key in the X-API-Key header. Every endpoint except /health requires it.
When: You used the wrong tier of key for the operation. The API uses a two-tier key model:
  • Partner Key — onboarding clients, listing companies, browsing controls.
  • Company Key — document submission, status polling, results retrieval, company/entity updates.
Using a Partner Key for a company-scoped operation (or vice versa) returns 403.Fix: Use the Company Key returned by POST /v2/onboard for all document operations; use the Partner Key for onboarding and partner-level listing. See Authentication.
When: The resource ID doesn’t exist, or it belongs to a different company than your key.The organization unit routes (/v2/organization-units*) answer 404 with genericErrors: Organization unit not found or access denied when the unit doesn’t exist, belongs to another company, or has another type than the type query parameter. See Organization Units.Fix: Confirm the ID and that you’re using the key for the company that owns the resource.
When: You uploaded a chunk to an upload session that has expired (sessions last 24 hours).Fix: Start a new session with POST /v2/documents/upload/start and re-upload. See Chunked Upload.
When: The request is well-formed but can’t be processed — e.g. submitting both organizationUnitId and complianceReviewId, or referencing a control that isn’t whitelisted for your partner. Examples from the v2 document routes:
  • POST /v2/documents/submit: Provide either complianceReviewId OR organizationUnitId, not both or neither.; an organizationUnitId that is not found or belongs to another company returns 422 (not 404) with Organization unit not found or access denied.
  • POST /v2/documents/upload/start with organizationUnitId: complianceFrameworkId is required when using organizationUnitId and controlId is required when using organizationUnitId.
On the organization unit routes, 422 means an unknown or archived type, a blank, too long or duplicate name, a PATCH without name and type, or a PATCH of an archived unit.The deprecated v1 routes keep their own messages: the v1 business entity routes answer 422 (not 404) when the business entity is not found, and the v1 submit and upload routes say BusinessEntity not found or access denied (v1 only). See Migrating to v2.Fix: Read the message; provide exactly one of organizationUnitId / complianceReviewId, and only reference frameworks/controls returned by GET /v2/compliance-frameworks.
When: You exceeded your tier’s request rate or the per-company submission limit.Fix: Back off and retry after the seconds given in the Retry-After response header. See Rate Limiting for the per-tier limits.
When: An unexpected server-side error.Fix: Retry with exponential backoff. If it persists, contact support with the request details and timestamp. See Support.