Errors and limits
Error shape
Errors Social Graph raises are JSON with one field:
{"error": "Redirect URI does not match the registered app"}
401is always{"error":"unauthorized"}. It doesn’t say why.5xxis always{"error":"internal error"}; details are kept out of responses.403bodies that name an app’s state are fixed codes you can match on:app_not_yet_active,app_disabled,app_suspended,app_terminated. Other messages are written for people and may change.
curl -sS https://socialgraph.stackwell.tech/api/graph-access/connections | grep -Fx '{"error":"unauthorized"}'
Some errors are not JSON. They come from parsing the request and are plain
text. On a route that takes a credential, Social Graph checks the credential
first, so a call without one gets 401 before any of these. POST /api/graph/token takes no credential header, so it shows them straight away:
| Status | Cause | Example body |
|---|---|---|
400 | A required query value is missing, or the body is not valid JSON | Failed to deserialize query string: missing field `clientId` |
413 | Body larger than 2 MiB | Failed to buffer the request body: length limit exceeded |
415 | Body sent without Content-Type: application/json | Expected request with `Content-Type: application/json` |
curl -sS -o /dev/null -w '%{http_code}\n' -X POST -H 'Content-Type: application/json' \
--data '{' https://socialgraph.stackwell.tech/api/graph/token | grep -Fx 400
A path Social Graph doesn’t know returns 404 with an HTML page, not JSON.
Status codes
| Status | Meaning |
|---|---|
200 | Done. Every successful call, including registration, returns 200. |
400 | A field breaks a rule: a JSON body field that is missing, has the wrong type or isn’t one of the values listed for it (matched exactly: "Web" is not web), a bad redirect URI, a redirect URI that doesn’t match the app, an expired code, a missing PKCE verifier, a malformed code_challenge. |
401 | No credential, or one Social Graph does not accept: an access token that expired, was replaced or revoked, or belongs to an app that is not active; a developer token from the wrong client. |
403 | The credential is valid but may not do this: no developer account, a wrong client secret or PKCE verifier, an app that is not active. |
404 | Unknown app, unknown or foreign approval code. |
409 | An approval code already used, or an appUserId another person in your app already holds. |
429 | Too many requests reached Social Graph at once. Retry with backoff. |
503 | A service Social Graph depends on, such as ChirpAuth, could not be reached. Retry later. |
Limits
| Limit | Value |
|---|---|
| Request body | 2 MiB |
| Approval code lifetime | 5 minutes, one use |
| Access token lifetime | 90 days |
code_challenge | 43 to 128 characters |
| Connection list, mutuals | 100 people, no paging |
Social Graph has no per-app quota on the endpoints a graph app calls. Under
heavy load it can return 429 or 5xx; treat both as “retry later”.