consent_scope

What it means

The Platform API returns consent_scope with HTTP 403 when a call includes subject and needs a world or scope the person did not grant. The person consented to different access than the call needs, so the request is refused rather than partially served.

Errors use the shape {"error":{"code":"…","message":"…","hint":"…"}}. The message reads "That person consented to different access than this call needs." The details field shows what the call needed and what was granted, so read both lists before you change the request. Codes are stable, so match on code and never on the message.

Why you are seeing it

You sent subject with a request for a world or scope outside the person's grant. The check compares the access the call needs against the access the person gave and returns consent_scope when the two sets do not line up.

This is not a transient failure. Sending the same payload, headers, and subject again produces the same 403. The details field is the useful part of the response because it separates what was needed from what was granted, which shows how far apart the two sets are.

consent_required is listed as a related code. If your integration handles both, branch on the code string rather than on message text or on the HTTP status alone.

How to fix it

Two fixes work. Ask only for what the person granted by changing the world or scope in the request to something that appears in the granted list. Or omit subject and make the call without it.

Start with details. If the needed list contains scopes that the granted list does not, narrow the call until the needed set fits inside the granted set. If the call cannot do its work with the smaller set, that is a consent mismatch for the person to resolve, not something a different header or a retry will clear.

Do not loop on retries. After you change the request, send it once and check the result. A corrected call either succeeds or returns a different code that tells you what else to address.

Handling it in code

Check error.code === "consent_scope" before reading anything else. Log the code, the hint, and the details together, because the hint carries the short explanation and details carries the two lists. Do not parse the message.

Treat this as a caller-side correction. Report the needed and granted lists to whoever owns the request instead of surfacing a generic failure. If your code path can run without subject, fall back to the no-subject call; otherwise fail the operation and name the scope that was missing.

Any retry policy you apply should exclude this code. Retrying identical input is wasted work, and the response will not change until the request or the subject does.