> ## Documentation Index
> Fetch the complete documentation index at: https://docs.digitalseaservice.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> RFC 7807 Problem Details — one shape for every error response, with a doc URL you can resolve.

Resource-endpoint errors use [RFC 7807 Problem
Details](https://datatracker.ietf.org/doc/html/rfc7807). Same shape every time:

```json theme={null}
{
  "type": "https://docs.digitalseaservice.com/errors/insufficient_scope",
  "title": "Insufficient scope",
  "status": 403,
  "detail": "This endpoint requires the seatime:read scope. Granted: profile:read.",
  "instance": "req_01HV9XK..."
}
```

The `Content-Type` is `application/problem+json`.

| Field | Meaning |
| - | - |
| `type` | A URL that resolves into these docs — one page per type, listed below. |
| `title` | Short, human-readable, machine-keyable label. Stable across status codes. |
| `status` | HTTP status, mirrored from the response line. |
| `detail` | Human-readable, context-specific message. Safe to surface to the partner-side support. |
| `instance` | The `X-Request-Id` of this request. Quote it when contacting support. |

<Note>
  **OAuth endpoint errors do not use Problem Details.** They follow
  [RFC 6749 §5.2](https://datatracker.ietf.org/doc/html/rfc6749#section-5.2)
  — shape is `{ "error": "...", "error_description": "..." }`. OAuth client
  libraries key off `response["error"]` and break otherwise. See
  [Authentication / failure modes](/authentication#failure-modes).
</Note>

## How to handle errors

1. **Branch on `type`, not on `detail`.** `type` URLs are stable. `detail`
   strings improve over time.
2. **Surface `instance` in your own logs.** Every API response (success or
   failure) includes `X-Request-Id` that matches `instance`. We can find the
   exact request in our audit log instantly given the request ID.
3. **Retry the right errors only.** `5xx` and `429` are retryable with
   backoff. `4xx` other than `429` are not — fix the request first.
4. **Map to your own messaging.** Don't show `type` URLs to end users. The
   URL is for your engineers and AI agents; users get your wording.

## Error catalog

Every `type:` URL in a Problem Details response resolves to one of these
pages:

<CardGroup cols={2}>
  <Card title="invalid_request (400)" href="/errors/invalid_request">
    Malformed request — missing parameter, bad format, schema validation
    failure.
  </Card>

  <Card title="invalid_token (401)" href="/errors/invalid_token">
    Missing, malformed, expired, or revoked access token.
  </Card>

  <Card title="insufficient_scope (403)" href="/errors/insufficient_scope">
    Token is valid but doesn't carry the scope this endpoint requires.
  </Card>

  <Card title="partner_suspended (403)" href="/errors/partner_suspended">
    Your partner account is suspended — an account-level state, not a token
    scope issue.
  </Card>

  <Card title="not_found (404)" href="/errors/not_found">
    Resource or route does not exist.
  </Card>

  <Card title="no_webhook_configured (409)" href="/errors/no_webhook_configured">
    You called the webhook self-test before registering a URL and signing
    secret.
  </Card>

  <Card title="rate_limit_exceeded (429)" href="/errors/rate_limit_exceeded">
    You've exceeded your per-minute or per-day budget. Check `Retry-After`.
  </Card>

  <Card title="internal_error (500)" href="/errors/internal_error">
    Something broke on our side. Quote `X-Request-Id` to support.
  </Card>

  <Card title="service_unavailable (503)" href="/errors/service_unavailable">
    An upstream DSS system was unreachable. Retry with backoff — never treat it
    as an empty answer.
  </Card>
</CardGroup>

Three further types are returned only by the partner-restricted
[Sponsorship API](/sponsorships/overview):

<CardGroup cols={2}>
  <Card title="account_requires_signup (409)" href="/errors/account_requires_signup">
    No DSS account yet — send the member to `signup_url` for normal signup.
  </Card>

  <Card title="email_already_premium (409)" href="/errors/email_already_premium">
    The crew member you tried to sponsor already pays for Premium themselves.
  </Card>

  <Card title="sponsorship_cap_reached (409)" href="/errors/sponsorship_cap_reached">
    Your program's seat cap is full.
  </Card>

  <Card title="entitlement_write_failed (502)" href="/errors/entitlement_write_failed">
    We could not grant Premium to the member, so no seat was billed. Retry.
  </Card>
</CardGroup>

## Request ID

Every response — success or error — carries `X-Request-Id`. On errors it also
matches the `instance` field of the Problem Details body. Quote it when you
contact support and we can find the exact audit log entry in seconds.

You can also send your own `X-Request-Id` on a request — we'll honour it and
include it on the response, which makes correlating your logs with ours
trivial.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.