Errors and result codes

SocialScope reports problems in four places: GraphQL errors on a request, resultCode on a Connect attempt, errorCode on a sync job, and reason or incompleteReason on data. This page lists every value a consumer can see and what your app should do about it. Treat any code you do not recognize as a retryable failure that shows no success, and log its correlationId.

GraphQL error shape

A failed request returns an errors array. Each error looks like this:

{
  "errors": [
    {
      "message": "RATE_LIMITED",
      "path": ["requestRefresh"],
      "extensions": {
        "code": "RATE_LIMITED",
        "correlationId": "4f1c2a9e-0b7d-4e7a-9a51-2a3f0c1d9e88",
        "retryAfterSeconds": 60
      }
    }
  ],
  "data": null
}

• extensions.code is one of the codes below. Branch on it, not on message.
• message is the code itself, except for the request-limit messages GraphQL alias limit exceeded, GraphQL depth limit exceeded, GraphQL cost limit exceeded, GraphQL operation limit exceeded and Operation batching disabled. Any other detail, such as a parse or validation error naming a bad field, is replaced by the bare code.
• extensions.correlationId is a UUID on every error. Log it and quote it when you ask for help.
• extensions.retryAfterSeconds appears only on some RATE_LIMITED errors.
• Do not rely on the HTTP status. Most failed operations arrive with HTTP 200. Parse, validation, limit and batching errors arrive with HTTP 400 and the same errors shape. A body over 64 KiB gets HTTP 413 before GraphQL runs, with no GraphQL body.

GraphQL error codes

Reads by connection status

A CONNECTED connection is checked again on every read. connection then throws instead of returning the row when:

connections reads every row on the page the same way, so one such account makes the whole list call fail with that code. Keep the connection IDs you received from Connect in your own database, read each one with connection, and map each error code to that account's state. Treat connections as a convenience. If it fails, fall back to per-ID reads rather than showing "no accounts".

Local codes from the sample helper

The sample helper in Authentication adds codes of its own. SocialScope never sends them.

Rate limits

There is no minimum interval between refreshes, but repeated requests for the same window or post while one is in flight return the existing job.

Connect result codes

connectSessionResult returns status, resultCode and creatorAction.

For every non-COMPLETED result, offer a retry in your app. Never fall back to your own provider OAuth.

creatorAction is null or REMOVE_APP_AT_PROVIDER. When set, ask the person to remove the app in their provider account settings, because a grant may still be active there. Treat any unknown value the same way. It can change from null to REMOVE_APP_AT_PROVIDER on a later read of the same attempt.

Sync job error codes

syncJob.errorCode explains a FAILED job, and in one case a SUCCEEDED one. A QUEUED job that is waiting to retry also carries the last error in errorCode, with nextRetryAt set. That is not a final failure.

Availability reasons

On a MetricObservation:

On a ContentItem:

In every case except AVAILABLE, show "not available", never 0.

Completeness reasons

pageInfo.incompleteReason and syncJob.incompleteReason:

A syncJob for a metrics refresh or lookup that could not read its post also sets completeForWindow: false and incompleteReason to CONTENT_NOT_OWNED, CONTENT_UNAVAILABLE, LOOKUP_INCOMPLETE or BAD_PROVIDER_ID. Treat any other value as incomplete too.

See Reading data.

Google identity outcomes

redeemGoogleIdentityResult.status is PENDING, COMPLETED, DENIED, FAILED or EXPIRED. A second redeem, a wrong proof or tenant, another app's attempt, an expired result, or identity turned off for your app all return the same NOT_FOUND. See Google identity.

Browser-side failures

These happen in the person's browser on SocialScope's host, not in your GraphQL calls. You learn about them by reading the attempt from your server.

In each case, let the person start again from your app. An unfinished attempt reads as EXPIRED once its 10-minute deadline passes.