Error Handling

The Scompler API uses standard GraphQL error conventions. HTTP status is always 200 — errors are in the response body.

Error Structure

{
  "errors": [
    {
      "message": "You don't have permission to perform this action.",
      "locations": [{ "line": 2, "column": 3 }],
      "path": ["updateContent"],
      "extensions": {
        "code": "FORBIDDEN",
        "details": {
          "requiredScope": "content:write"
        }
      }
    }
  ]
}

Error Codes Reference

Code	HTTP Analogy	Description
UNAUTHENTICATED	401	No valid token provided
FORBIDDEN	403	Token lacks required permissions
NOT_FOUND	404	Resource does not exist
VALIDATION_ERROR	422	Input failed validation
RATE_LIMITED	429	Too many requests
CONFLICT	409	Conflicting operation (e.g., duplicate)
INTERNAL_SERVER_ERROR	500	Unexpected server error

Partial Success

GraphQL allows partial success — some fields succeed while others fail:

{
  "data": {
    "content": { "id": "...", "title": "..." },
    "analytics": null
  },
  "errors": [{
    "message": "Analytics data unavailable",
    "path": ["analytics"],
    "extensions": { "code": "INTERNAL_SERVER_ERROR" }
  }]
}

Always check both data and errors in your response handler.