When working with the Partner API, errors can occur for a variety of reasons — from invalid headers to malformed input. This page outlines how we communicate those errors, how you can distinguish between different types, and how to get help if something doesn’t seem right.

​
🧭 Two types of errors

The Partner API uses GraphQL, which means responses can contain both:

  1. GraphQL errors – for structural or authentication-level issues

  2. User errors – for problems with your request’s input, like validation failures

​
1. GraphQL errors

These errors appear in the top-level errors array of the response. They are used to communicate problems with the request itself — typically related to authorization, malformed headers, or server-side issues.

​
Example

{
  "errors": [
    {
      "message": "Invalid request `X-Ownright-Client-ID` header, could not find registered API client.",
      "code": "INVALID_API_CLIENT"
    }
  ]
}
Error CodeHTTP StatusDescription
INVALID_API_CLIENT403Used when the supplied X-Ownright-Client-ID header is invalid.
INVALID_TOKEN403Used when the supplied access or refresh token is invalid.
EXPIRED_TOKEN403Used when the supplied access or refresh token is expired.
BAD_REQUEST400Used when the request is incorrectly formatted.
INTERNAL_SERVER_ERROR500Used when there is a server error (likely a bug that needs to be fixed).

When these errors occur, the HTTP status code of the response will reflect the issue (e.g. 403 Forbidden for an invalid token).

​
2. User errors

User errors are returned inside the data object of a successful GraphQL response. These indicate issues with the input provided — for example, a missing field or an invalid value.

{
  "data": {
    "purchaseReferralCreate": {
      "userErrors": [
        {
          "code": "INVALID_INPUT",
          "message": "Email must be a valid format."
        }
      ]
    }
  }
}

​
Handling user errors

  • User errors do not result in a failed HTTP request. The status will be 200 OK but the mutation will have no effect.

  • Always check for userErrors in the response, especially when calling mutations.

You can build resilient integrations by displaying these error messages to your clients or logging them for review.

​
🏷️ Request ID for debugging

Every Partner API response includes a X-Request-Id header. If you’re seeing an unexpected error or behavior, please include this Request-Id when contacting support — it allows us to trace and investigate the request quickly.

X-Request-Id: req_8e9f2aa02189423d9b2a71e9c4b15e1d

​
🛠 Tips for working with errors

  • Log GraphQL and user errors separately — they represent different classes of problems.

  • Use GraphQL IDEs (e.g. Insomnia, GraphiQL) to catch schema errors before deployment.

  • Always include a Request-Id when reporting issues to [email protected].