Errors

When a request fails, the Titan Public API returns a JSON body containing a single top-level error object. Its shape is the same for every endpoint and every status code, so one error handler covers your whole integration.

The field to act on is error.reason — a constant such as RESOURCE_NOT_FOUND that names the specific thing that went wrong. The HTTP status code tells you the broad category of failure; reason tells you which failure within that category, so a 400 caused by a missing field is distinguishable from a 400 caused by a malformed identifier. Write your error handling as a switch on error.reason, and use error.message for logs and debugging rather than for control flow.

{
  "error": {
    "code": 404,
    "message": "No observation found for ORN: orn:scs:observation:...",
    "status": "NOT_FOUND",
    "reason": "RESOURCE_NOT_FOUND"
  }
}

These four fields are the whole contract. Ignore any other field you see in a response body — nothing else is part of the public error envelope, and anything extra may disappear without notice.

Each status code has its own set of reason values, listed below.

Handle the reasons your integration cares about and fall back to a generic message for the rest. New reasons are added over time, and one you do not recognise is always safe to treat as a generic failure of its status code.

status: INVALID_ARGUMENT, or FAILED_PRECONDITION for UNSUPPORTED_API_VERSION.

status: UNAUTHENTICATED.

:::info

Some authentication failures are rejected before the request reaches the service; those responses carry no reason field, so a switch on error.reason falls through to your default case. Treat any 401 without a reason as "get a new token and retry once".

When the service itself rejects the credential, the response carries one of the reasons below.

:::

status: PERMISSION_DENIED.

status: NOT_FOUND.

status: ALREADY_EXISTS, FAILED_PRECONDITION, or ABORTED.

A 409 with status ABORTED and no reason means a request with the same Idempotency-Key is still being processed. Retry it later with the same key.

status: INTERNAL.

INTERNAL_ERROR and REASON_UNSPECIFIED are safe to retry; PV1_DOMAIN_NOT_CONFIRMED is not — see Retry guidance.

if (response.status >= 400) {
  const body = await response.json();
  const reason = body?.error?.reason;

  switch (reason) {
    case 'RESOURCE_NOT_FOUND':
      // show "not found" UI
      break;
    case 'VIEW_NOT_ENTITLED':
      // re-fetch with non-VRM ORN, or prompt re-auth
      break;
    case 'MISSING_REQUIRED_FIELD':
      // surface validation hint to the user
      break;
    default:
      // treat as a generic failure for this status
  }
}

If you generate hooks via @securityscorecard/react-query, use the isErrorStatus guard to narrow the error type:

import { isErrorStatus } from '@securityscorecard/react-query';

const { error } = useGetObservationByOrn(orn);

if (isErrorStatus(error, 403)) {
  // error.response.data is PermissionDeniedError
  const reason = error.response.data.error?.reason;
  // reason is narrowed to 'ORN_DOMAIN_NOT_ALLOWED' | 'VIEW_NOT_ENTITLED' | 'REASON_UNSPECIFIED' | undefined
}

When opening a support ticket, include:

1. HTTP status and error.reason.
2. The full error.message from the response.
3. Approximate timestamp (UTC).
4. Minimal request example (method, path, headers other than Authorization).
5. What you expected vs. what you observed.