Errors

When a request fails, the Dealroom API returns a JSON envelope with a consistent shape and an HTTP status code. Error codes are stable strings — switch on error.code in your client rather than parsing the human-readable message.

Response envelope

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Human-readable description of what went wrong",
    "details": { "filter": "launch_date" }
  }
}

Field	Description
`code`	Stable identifier — use this for programmatic error handling
`message`	Human-readable explanation. Safe to surface in dev tools, but the exact wording may change
`details`	Optional extra context. May be absent, an object (e.g. `{ "filter": "launch_date" }`), or an array of `{ "path", "message" }` entries for schema-validation errors

Error-code catalog

Code	HTTP	When it happens	How to fix
`VALIDATION_ERROR`	`400`	Missing/invalid header, or a request body/parameter fails validation	Inspect `message` and `details` for the offending field, correct, retry
`INVALID_ENTITY_ID`	`400`	Entity ID isn’t a valid UUID (path or request-body ID). Some endpoints (e.g. funds) take a numeric ID and also return this code	Entity routes take a UUID, e.g. `/data/entities/{uuid}`; numeric IDs are rejected there. For funds and similar, use the numeric ID
`UNKNOWN_FILTER`	`400`	Filter key isn’t registered for the scope	See the Filters reference for available filters per scope
`FILTER_PARSE_ERROR`	`400`	Filter expression has a syntax error	Check `and()` / `or()` parentheses and the `field[op]:value` form
`FILTER_VALIDATION_ERROR`	`400`	Filter value is invalid — wrong type, or (for enum filters) not in the accepted value set	Check the value type in the Filters reference; for enums, look values up via `/reference/filters/{key}/values`
`UNSUPPORTED_OPERATOR`	`400`	Operator not allowed for that filter	Use one of the operators listed in `message`
`PAGINATION_DEPTH_EXCEEDED`	`400`	The requested page exceeds the caller’s pagination-depth cap	Restart from an earlier page or request a smaller range
`UNAUTHORIZED`	`401`	Missing or invalid Bearer token	Re-fetch a token via Authentication
`FORBIDDEN`	`403`	Token is valid but lacks the required permission	Check your API key’s scope list in Settings > API
`ACCOUNT_REQUIRED`	`403`	The requested capability requires a signed-in Dealroom account	Sign in with an eligible account before retrying
`INSTANCE_ACCESS_REQUIRED`	`403`	Signed in, but the account has not been granted access to this Dealroom instance (e.g. beta)	Ask your Dealroom contact for access to the instance, then sign in again so the new permission is in your token
`LIST_LOCKED`	`403`	A legacy-mirrored list is read-only	Clone the list before editing it
`NOT_FOUND`	`404`	Resource ID doesn’t exist or isn’t visible to your key	Verify the ID; check permissions if the entity exists in another dataset
`PATH_RENAMED`	`404`	A renamed path is used after its redirect window has expired	Follow the replacement path in `details`
`ENDPOINT_REMOVED`	`410`	An endpoint was removed without a direct replacement	Check `details` and the changelog for the supported workflow
`RATE_LIMITED`	`429`	The API key exceeded its request rate	Respect `Retry-After` and retry with backoff
`CREDITS_EXHAUSTED`	`402`	Your team’s credits are used up, or none were granted yet. Returned under `/data` and `/analytics`; `/reference` stays free — see Credits	Check your team’s balance on the API keys settings page and contact Dealroom to add credits. Don’t retry until they are added
`INTERNAL_SERVER_ERROR`	`500`	Unclassified server-side failure	Retry with backoff. If persistent, contact support with the response payload
`DATABASE_ERROR`	`500`	Database query failed (e.g. constraint violation)	Retry. If persistent, contact support
`SCHEMA_ERROR`	`500`	Database schema mismatch (internal)	Should never reach clients; contact support if you see one
`EXTERNAL_SERVICE_ERROR`	`502/503`	Downstream service unavailable (currently Auth0 Management API)	Retry with backoff
`SERVICE_UNAVAILABLE`	`503`	The API is temporarily unavailable, or your team’s credits could not be checked for a moment	Retry with backoff
`QUERY_TIMEOUT`	`504`	Query exceeded the 15-second execution budget	Narrow the query: add filters, reduce `limit`, or use an aggregate endpoint

Clients pinned to an API-Version before 2026-10-09 receive 422 instead of 400 in three cases: a request body or parameter that fails schema validation; a VALIDATION_ERROR the API returned as 422 before that version — a rejected /platform write (list categories and members, ecosystem limits and scopes), a filter key without value lookup on /reference/filters/{key}/values, or ecosystem_id filters nested too deep; and a FILTER_PARSE_ERROR from a filter that is being saved (a list created from a filter, an ecosystem scope). Branch on code, which is the same in every version.

Common scenarios

Invalid filter expression

curl -g "https://api.beta.dealroom.app/data/entities?filter=launch_date[invalid_op]:2020" ...

{
  "error": {
    "code": "UNSUPPORTED_OPERATOR",
    "message": "Operator 'invalid_op' not supported for filter 'launch_date'. Allowed operators: eq, neq, gt, gte, lt, lte",
    "details": { "filter": "launch_date" }
  }
}

Invalid enum value

Enum filters (round_type, preferred_round, investor_type, article_type) accept a closed, case-insensitive value set. An unknown value returns 400 rather than an empty result — discover valid values via /reference/filters/{key}/values.

curl -g "https://api.beta.dealroom.app/data/transactions?filter=round_type[eq]:seriesa" ...

{
  "error": {
    "code": "FILTER_VALIDATION_ERROR",
    "message": "Invalid value for filter 'round_type': \"seriesa\". See /reference/filters/round_type/values for accepted values.",
    "details": { "filter": "round_type" }
  }
}

Missing required header

The API requires Authorization on every authenticated request. API-key requests additionally require X-Client-Id set to the key’s client_id. The status code depends on which header is missing:

Missing Authorization → 401 UNAUTHORIZED
Missing X-Client-Id on an API-key request → 400 VALIDATION_ERROR

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "X-Client-Id header is required for API key requests"
  }
}

Expired token

After your access_token expires (default 24h):

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Token has expired"
  }
}

Refresh the token via the OAuth2 client-credentials flow. See the Quickstart for the token request and Authentication for production caching guidance.

Query timeout

A heavy aggregate or unfiltered list query may exceed the 15-second execution budget:

{
  "error": {
    "code": "QUERY_TIMEOUT",
    "message": "Query took too long to execute (15s timeout)"
  }
}

Narrow the query (add filters, reduce limit) or switch to a purpose-built aggregate endpoint instead of paging through raw entities.

Cloudflare edge blocks

Cloudflare sits in front of the API and can reject a request before it reaches the API. An edge block returns 403 with an HTML body (content-type: text/html) instead of the JSON error envelope; the API itself always answers with JSON. Two edge blocks to know about:

Banned User-Agent: some default HTTP-client signatures, notably Python’s urllib (Python-urllib/3.x), are blocked even when the request is otherwise valid. The HTML body contains error code: 1010.
Missing Authorization: a request without an Authorization header gets a browser challenge page (“Just a moment…”, with a cf-mitigated: challenge response header) instead of the API’s 401.

Fix the first by setting an explicit User-Agent header identifying your integration, for example my-app/1.0. Clients such as cURL, python-requests, Node.js fetch, and Go are not affected. Fix the second by always sending the Authorization header, even on exploratory requests.

Handling errors

Switch on error.code — it’s stable across API versions. Messages may change for clarity.

try {
  const { data } = await dealroom.get("/data/entities", { params });
  return data;
} catch (err) {
  const code = err.response?.data?.error?.code;

  switch (code) {
    case "UNAUTHORIZED":
      // Refresh the token and retry
      break;
    case "QUERY_TIMEOUT":
      // Narrow the query (more filters, smaller limit) or use an aggregate endpoint
      break;
    case "VALIDATION_ERROR":
    case "UNKNOWN_FILTER":
    case "FILTER_VALIDATION_ERROR":
    case "UNSUPPORTED_OPERATOR":
    case "FILTER_PARSE_ERROR":
    case "INVALID_ENTITY_ID":
      // Bug in your request — surface to your dev team
      break;
    case "NOT_FOUND":
      // Expected for some lookups; handle as a business case
      break;
    default:
    // 5xx — retry with exponential backoff
  }
}

Treat the message field as informative, not contractual. Always switch on code.

Endpoint-specific errors

Each endpoint may return a subset of these codes plus endpoint-specific ones. See the API Reference overview for the catalog per endpoint.

Authentication

Handle token expiry, missing scopes, and credential rotation in production.

Rate limits

Respond to 429 errors with the correct retry behavior.

Getting Started

Examples

Agents

Concepts

References

Response envelope

Error-code catalog

Common scenarios

Invalid filter expression

Invalid enum value

Missing required header

Expired token

Query timeout

Cloudflare edge blocks

Handling errors

Endpoint-specific errors

Further reading

Authentication

Rate limits

​Response envelope

​Error-code catalog

​Common scenarios

​Invalid filter expression

​Invalid enum value

​Missing required header

​Expired token

​Query timeout

​Cloudflare edge blocks

​Handling errors

​Endpoint-specific errors

​Further reading

Authentication

Rate limits

Response envelope

Error-code catalog

Common scenarios

Invalid filter expression

Invalid enum value

Missing required header

Expired token

Query timeout

Cloudflare edge blocks

Handling errors

Endpoint-specific errors

Further reading