Error Reference

This page is a quick reference for the error envelope returned by the Worksome GraphQL API. For a detailed guide on handling errors in your code, see Error Handling.

Error envelope

Every GraphQL error returned by the gateway includes an extensions.code field that identifies the broad failure mode. Use the code (not the message) to drive your control flow. Many platform-side errors also include a serviceName and a structured validation map.

Validation errors

Validation errors come back as DOWNSTREAM_SERVICE_ERROR with an extensions.validation map of dot-notation field paths to messages.

{
  "errors": [
    {
      "message": "Validation failed for the field [createDraftHire].",
      "path": ["createDraftHire"],
      "extensions": {
        "validation": {
          "input.startDate": ["The start date is not a valid date."],
          "input.trustedContact": ["The selected input.trusted contact is invalid."]
        },
        "serviceName": "platform",
        "code": "DOWNSTREAM_SERVICE_ERROR"
      }
    }
  ]
}

Common validation errors

Authentication errors

A missing or invalid bearer token is also wrapped as DOWNSTREAM_SERVICE_ERROR, with the platform’s api guard listed in extensions.guards.

{
  "errors": [
    {
      "message": "Unauthenticated.",
      "extensions": {
        "guards": ["api"],
        "serviceName": "platform",
        "code": "DOWNSTREAM_SERVICE_ERROR"
      }
    }
  ]
}

Authorization errors

When the token is valid but the operation is not allowed for the authenticated user (or for the requested record), you also receive a DOWNSTREAM_SERVICE_ERROR. The envelope has no machine-readable “authorization” tag — discriminate by the absence of a validation map plus the operation path and message.

{
  "errors": [
    {
      "message": "You are not authorized to perform this action.",
      "path": ["terminateHire"],
      "extensions": {
        "serviceName": "platform",
        "code": "DOWNSTREAM_SERVICE_ERROR"
      }
    }
  ]
}

Query errors

The gateway validates the query against the schema before reaching the platform. Field/argument/type mismatches surface as GRAPHQL_VALIDATION_FAILED; pure syntax errors surface as GRAPHQL_PARSE_FAILED.

{
  "errors": [
    {
      "message": "Cannot query field \"nonExistent\" on type \"Hire\".",
      "locations": [{ "line": 3, "column": 5 }],
      "extensions": {
        "code": "GRAPHQL_VALIDATION_FAILED"
      }
    }
  ]
}

Bad request errors

The gateway rejects HTTP requests that do not conform to its expectations (e.g. missing Content-Type, GET without an apollo-require-preflight header) before reaching GraphQL.

{
  "errors": [
    {
      "message": "This operation has been blocked as a potential Cross-Site Request Forgery (CSRF). Please either specify a 'content-type' header (with a type that is not one of application/x-www-form-urlencoded, multipart/form-data, text/plain) or provide a non-empty value for one of the following headers: x-apollo-operation-name, apollo-require-preflight",
      "extensions": {
        "code": "BAD_REQUEST"
      }
    }
  ]
}

Server errors

If the platform itself fails (timeout, unhandled exception), the gateway forwards a DOWNSTREAM_SERVICE_ERROR with serviceName: "platform" and a generic message. These are typically transient — retry with exponential backoff (1s, 2s, 4s) up to 3 times. If the error persists, contact Support with the full error response and your query.

Rate limiting

The Worksome platform applies rate limiting per API token (default 60 requests per minute). When you exceed the limit, the gateway forwards a DOWNSTREAM_SERVICE_ERROR; the gateway does not currently expose X-RateLimit-* headers on the response. Treat repeated DOWNSTREAM_SERVICE_ERROR responses with a “Too Many Requests” message as rate-limit signals, and back off. See Rate Limiting for details.

Partial responses

GraphQL can return both data and errors in the same response. Always check the errors array even when data is present.

{
  "errors": [
    {
      "message": "You are not authorized to access this field.",
      "path": ["hire", "rate"],
      "extensions": {
        "serviceName": "platform",
        "code": "DOWNSTREAM_SERVICE_ERROR"
      }
    }
  ],
  "data": {
    "hire": {
      "id": "SGlyZTox",
      "rate": null
    }
  }
}

Fields that error return null in the data, with corresponding entries in the errors array. Use the available data and handle individual field errors gracefully.