Waafir
Platform API (/v1)

Error codes

A refused request usually answers with a JSON body carrying a human-readable error and a machine-readable code:

{ "error": "This access token is not scoped to this dataroom", "code": "PAT_DATAROOM_SCOPE" }

Branch on code when it is present, not on error, because the message is written for people and may be reworded. Some refusals carry no code at all, such as certain 404 responses, so fall back to the HTTP status. Some errors add fields, such as fieldErrors on a validation failure. The HTTP status column lists the statuses the code is known to arrive with. Varies means the status is set by the endpoint.

The list below is generated from the platform's route tree. It is the known minimum, not an exhaustive list: it includes the codes the authentication layer and the scanned gate helpers produce and the codes written directly in handlers. Codes returned by other helpers a handler calls do not appear here. Each endpoint on the endpoints page lists its own known codes. Handle an unlisted code by its HTTP status.

CodeHTTP statusMeaning
ACCESS_EXPIRED403See the error message in the response body.
ADDON_NOT_PURCHASEDVariesThe endpoint needs an add-on the organization has not purchased, such as portfolio monitoring.
AI_BUDGET_UNAVAILABLE503AI spend accounting is temporarily unavailable, so the request was refused rather than run unmetered. Retry shortly.
AI_DAILY_BUDGET_EXCEEDED429The organization's daily AI spend cap has been reached. Retry after the daily budget resets.
ai_disabled403AI features are turned off for this organization.
BAD_REQUEST400The request was malformed. The usual causes are an unknown query parameter on an endpoint that rejects them, or an invalid value.
BLOCKED_FILE_TYPEVariesSee the error message in the response body.
CHECK_VIOLATIONVariesThe submitted row breaks a data invariant, such as an amount outside its allowed range. fieldErrors names the field.
COMMIT_FAILEDVariesThe import could not be committed in its current state. Check its status before retrying.
CONFLICTVariesThe request conflicts with the resource's current state. A typical cause is creating something that already exists.
DATAROOM_REQUIREDVariesSee the error message in the response body.
FILE_NOT_FOUNDVariesNo such file, or none the caller can see.
FILE_TOO_LARGEVariesSee the error message in the response body.
FORBIDDEN403The caller is authenticated but lacks the role, or the data room access, that this endpoint requires. See Required role on the endpoint.
GRANTEE_NOT_FOUNDVariesThe user or group the grant names does not exist in this organization.
GRANTEE_NOT_IN_DATAROOMVariesThe grantee has no access to this data room, so a file-level grant inside it would have no effect.
ID_CONFLICTVariesA record with this caller-supplied id already exists. Ids are chosen by the caller and must be unique.
IDEMPOTENCY_CONFLICTVariesThis idempotency key was already used with a different request. Reuse a key only to retry the identical request.
IDEMPOTENCY_KEY_REUSEDVariesThis idempotency key already started an import. The response's importId identifies it, so poll that import instead of starting another.
INTERNAL_ERRORVariesSee the error message in the response body.
INVALID_BODYVariesThe request body is missing, is not valid JSON, or does not match the expected shape.
INVALID_STATUS_TRANSITIONVariesThe requested status change is not allowed from the record's current status.
IP_BLOCKED403The organization has an IP allowlist, and the request came from an address outside it.
MFA_CHALLENGE_REQUIRED403The organization enforces two-factor authentication and this session has not completed a challenge.
MFA_SETUP_REQUIRED403The organization enforces two-factor authentication and the user has not enrolled.
MONITORING_INVESTOR_FORBIDDEN403See the error message in the response body.
NDA_REQUIRED403See the error message in the response body.
NOT_FOUNDVariesNo such resource, or none the caller can see.
ORG_CONTEXT_STALE409See the error message in the response body.
ORG_NOT_FOUNDVariesThe caller's organization could not be found.
ORGANIZATION_REQUIREDVariesThe credential is not attached to an organization, so an organization-scoped read has nothing to answer about.
PAID_PLAN_REQUIRED402The organization's plan does not include this capability.
PAT_DATAROOM_SCOPE403The token is restricted to specific data rooms. Either this data room is not one of them, or the endpoint is organization-wide and cannot be called with a data-room-restricted token.
PAT_GRANT_REQUIRED403The endpoint needs an opt-in permission that this personal access token was created without. The endpoint's Token permission names it: for example, Read document content (content:read) to receive file contents, Read engagement analytics (analytics:read) to read the activity feed and engagement, or Send to people outside your organization (external:send) to invite team members or to give someone outside the deal team access, or more access, to documents. Some endpoints need it only for some requests, and the row says which. Create a token with that permission turned on. Service tokens are not affected.
PAT_PATH_MALFORMED403The request path is not validly encoded. It contains a dot-segment (. or ..), an encoded slash, or an undecodable escape, so it cannot be matched against the token's permissions and is refused. Send each path segment percent-encoded exactly once.
PAT_ROLE_CEILING403The token carries a role ceiling below the role this endpoint requires. The effective role is the lower of the user's live role and the token's ceiling.
PAT_SCOPE_INSUFFICIENT403The token's scope is below what the endpoint needs. A read token cannot call a write endpoint, for example. Issue a token with a higher scope.
PAYMENT_REQUIREDVariesSee the error message in the response body.
PIPELINE_PAUSED503See the error message in the response body.
PORTFOLIO_NOT_FOUNDVariesThe referenced portfolio does not exist in this organization.
RATE_LIMITED429Too many requests from this identity. Back off and retry. The endpoint's per-minute ceiling is listed where it declares one.
REFERENCED_ENTITY_NOT_FOUNDVariesThe body references another record, such as a loan or borrower, by an id that does not exist in this organization.
SESSION_EXPIRED401A browser session timed out under the organization's session policy. Sign in again.
SIZE_LIMIT_EXCEEDEDVariesSee the error message in the response body.
SUBSCRIPTION_LAPSED402See the error message in the response body.
TRIAL_EXPIRED402See the error message in the response body.
UNAUTHORIZED401, 403, 404, 429, 503The request could not be authenticated or admitted. At 401 the token is missing, unknown, expired or revoked. At 403 or 404 the resource is outside what the caller can reach; an id in another organization is treated as not found, so a response does not confirm another tenant's data. At 429 or 503 authentication itself is throttled or temporarily unavailable, so retry with backoff.
UNKNOWN_EXPORT_TYPEVariesThe export type requested is not one this endpoint produces.
UNKNOWN_KINDVariesThe import kind is not one this endpoint accepts. The response's allowed lists the valid values.
UPLOAD_INCOMPLETEVariesSee the error message in the response body.
VALIDATION_ERRORVariesSee the error message in the response body.
VALIDATION_FAILEDVariesOne or more fields failed validation. The response's fieldErrors names each field and the reason.