Read the Refusal

Troubleshooting goca starts with a habit: read the refusal, verbatim, before forming a theory. Every API failure uses one structured envelope:

{ "error": {
    "id": "GOCA-E1427",
    "code": "sort_needs_narrower_filter",
    "message": "subject sorting needs a working set under 10,000 rows",
    "remediation": "add a CA, template or time filter",
    "requestId": "...",
    "docs": "/docs/troubleshooting#GOCA-E1427" } }

Five fields, five uses. The stable id resolves in the embedded troubleshooting chapter and is carried into console and structured logs. The code is what automation keys on — never the English text, which may gain detail between releases. The message names what was refused; remediation names the fix, because goca's refusals are written to be acted on. And the requestId correlates this exact request across the console, the ops log and a support conversation. HTTP status keeps its conventional meaning: 403 is authenticated-but-out-of-scope, 409 is conflict, 503 is a dependency down and retryable.

Most "bugs" in the rest of this section dissolve into a refusal that was paraphrased instead of read.

Now I read the envelope before I form a theory.