Errors

REST errors use a structured envelope:

{
  "error": {
    "code": "API_SCOPE_REQUIRED",
    "message": "API_SCOPE_REQUIRED: research:write"
  }
}

Treat error.code as the machine-readable category and error.message as diagnostic context.

Status	Meaning	Recovery
`400`	Input, validation, or request precondition failed.	Correct the request; do not retry unchanged.
`401`	API key is missing, invalid, expired, or revoked.	Supply a current key.
`403`	The key lacks the required scope.	Use a least-privilege key that includes that scope.
`404`	The resource or route is absent or not visible in this Workspace.	Verify the path, ID, and Workspace. Do not infer another tenant owns it.
`429`	Admission or rate limit reached.	Honor `Retry-After` when present and back off with jitter.
`5xx`	RISOS or a required provider is unavailable.	Retry safe reads; retry writes only with the documented idempotency strategy.

For POST /research-jobs, preserve the same Idempotency-Key when retrying an uncertain request.