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.
| Code | HTTP status | Meaning |
|---|---|---|
ACCESS_EXPIRED | 403 | See the error message in the response body. |
ADDON_NOT_PURCHASED | Varies | The endpoint needs an add-on the organization has not purchased, such as portfolio monitoring. |
AI_BUDGET_UNAVAILABLE | 503 | AI spend accounting is temporarily unavailable, so the request was refused rather than run unmetered. Retry shortly. |
AI_DAILY_BUDGET_EXCEEDED | 429 | The organization's daily AI spend cap has been reached. Retry after the daily budget resets. |
ai_disabled | 403 | AI features are turned off for this organization. |
BAD_REQUEST | 400 | The request was malformed. The usual causes are an unknown query parameter on an endpoint that rejects them, or an invalid value. |
BLOCKED_FILE_TYPE | Varies | See the error message in the response body. |
CHECK_VIOLATION | Varies | The submitted row breaks a data invariant, such as an amount outside its allowed range. fieldErrors names the field. |
COMMIT_FAILED | Varies | The import could not be committed in its current state. Check its status before retrying. |
CONFLICT | Varies | The request conflicts with the resource's current state. A typical cause is creating something that already exists. |
DATAROOM_REQUIRED | Varies | See the error message in the response body. |
FILE_NOT_FOUND | Varies | No such file, or none the caller can see. |
FILE_TOO_LARGE | Varies | See the error message in the response body. |
FORBIDDEN | 403 | The caller is authenticated but lacks the role, or the data room access, that this endpoint requires. See Required role on the endpoint. |
GRANTEE_NOT_FOUND | Varies | The user or group the grant names does not exist in this organization. |
GRANTEE_NOT_IN_DATAROOM | Varies | The grantee has no access to this data room, so a file-level grant inside it would have no effect. |
ID_CONFLICT | Varies | A record with this caller-supplied id already exists. Ids are chosen by the caller and must be unique. |
IDEMPOTENCY_CONFLICT | Varies | This idempotency key was already used with a different request. Reuse a key only to retry the identical request. |
IDEMPOTENCY_KEY_REUSED | Varies | This idempotency key already started an import. The response's importId identifies it, so poll that import instead of starting another. |
INTERNAL_ERROR | Varies | See the error message in the response body. |
INVALID_BODY | Varies | The request body is missing, is not valid JSON, or does not match the expected shape. |
INVALID_STATUS_TRANSITION | Varies | The requested status change is not allowed from the record's current status. |
IP_BLOCKED | 403 | The organization has an IP allowlist, and the request came from an address outside it. |
MFA_CHALLENGE_REQUIRED | 403 | The organization enforces two-factor authentication and this session has not completed a challenge. |
MFA_SETUP_REQUIRED | 403 | The organization enforces two-factor authentication and the user has not enrolled. |
MONITORING_INVESTOR_FORBIDDEN | 403 | See the error message in the response body. |
NDA_REQUIRED | 403 | See the error message in the response body. |
NOT_FOUND | Varies | No such resource, or none the caller can see. |
ORG_CONTEXT_STALE | 409 | See the error message in the response body. |
ORG_NOT_FOUND | Varies | The caller's organization could not be found. |
ORGANIZATION_REQUIRED | Varies | The credential is not attached to an organization, so an organization-scoped read has nothing to answer about. |
PAID_PLAN_REQUIRED | 402 | The organization's plan does not include this capability. |
PAT_DATAROOM_SCOPE | 403 | The 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_REQUIRED | 403 | The 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_MALFORMED | 403 | The 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_CEILING | 403 | The 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_INSUFFICIENT | 403 | The 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_REQUIRED | Varies | See the error message in the response body. |
PIPELINE_PAUSED | 503 | See the error message in the response body. |
PORTFOLIO_NOT_FOUND | Varies | The referenced portfolio does not exist in this organization. |
RATE_LIMITED | 429 | Too many requests from this identity. Back off and retry. The endpoint's per-minute ceiling is listed where it declares one. |
REFERENCED_ENTITY_NOT_FOUND | Varies | The body references another record, such as a loan or borrower, by an id that does not exist in this organization. |
SESSION_EXPIRED | 401 | A browser session timed out under the organization's session policy. Sign in again. |
SIZE_LIMIT_EXCEEDED | Varies | See the error message in the response body. |
SUBSCRIPTION_LAPSED | 402 | See the error message in the response body. |
TRIAL_EXPIRED | 402 | See the error message in the response body. |
UNAUTHORIZED | 401, 403, 404, 429, 503 | The 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_TYPE | Varies | The export type requested is not one this endpoint produces. |
UNKNOWN_KIND | Varies | The import kind is not one this endpoint accepts. The response's allowed lists the valid values. |
UPLOAD_INCOMPLETE | Varies | See the error message in the response body. |
VALIDATION_ERROR | Varies | See the error message in the response body. |
VALIDATION_FAILED | Varies | One or more fields failed validation. The response's fieldErrors names each field and the reason. |
Endpoints
Every endpoint of the Waafir /v1 Platform API: method, path, the role and token scope it needs, accepted query parameters, rate limit and the error codes known to be reachable. Generated from the platform's route tree.
Investor permissioning, roles, and lifecycle
How investors get into a Waafir data room, what they can do once in, and how access is granted, scoped, extended, and revoked. Covers the IAM v2 role model, dataroom-level permissions, the share-link and guest-access flow, NDA gating, and the full invite-to-revoke lifecycle.