Resource-endpoint errors use RFC 7807 Problem Details. Same shape every time: 
{
  "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.
FieldMeaning
typeA URL that resolves into these docs — one page per type, listed below.
titleShort, human-readable, machine-keyable label. Stable across status codes.
statusHTTP status, mirrored from the response line.
detailHuman-readable, context-specific message. Safe to surface to the partner-side support.
instanceThe X-Request-Id of this request. Quote it when contacting support.
OAuth endpoint errors do not use Problem Details. They follow RFC 6749 §5.2 — shape is { "error": "...", "error_description": "..." }. OAuth client libraries key off response["error"] and break otherwise. See Authentication / failure modes.

​
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:

invalid_request (400)

Malformed request — missing parameter, bad format, schema validation failure.

invalid_token (401)

Missing, malformed, expired, or revoked access token.

insufficient_scope (403)

Token is valid but doesn’t carry the scope this endpoint requires.

partner_suspended (403)

Your partner account is suspended — an account-level state, not a token scope issue.

not_found (404)

Resource or route does not exist.

no_webhook_configured (409)

You called the webhook self-test before registering a URL and signing secret.

rate_limit_exceeded (429)

You’ve exceeded your per-minute or per-day budget. Check Retry-After.

internal_error (500)

Something broke on our side. Quote X-Request-Id to support.

​
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.