> ## Documentation Index
> Fetch the complete documentation index at: https://dev.ownright.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors and response codes

> Understand how our server communicates error states

When working with the Ownright Developer Platform, 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

Our APIs use GraphQL, which means responses can contain both:

<ol>
  <li>GraphQL errors – for structural or authentication-level issues</li>

  <li>
    User errors – for problems with your request's input, like validation
    failures
  </li>
</ol>

### 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

```json theme={null}
{
  "errors": [
    {
      "message": "Invalid request `X-Ownright-Client-ID` header, could not find registered API client.",
      "code": "INVALID_API_CLIENT"
    }
  ]
}
```

| Error Code              | HTTP Status | Description                                                              |
| ----------------------- | ----------- | ------------------------------------------------------------------------ |
| `INVALID_API_CLIENT`    | 403         | Used when the supplied `X-Ownright-Client-ID` header is invalid.         |
| `INVALID_TOKEN`         | 403         | Used when the supplied access or refresh token is invalid.               |
| `EXPIRED_TOKEN`         | 403         | Used when the supplied access or refresh token is expired.               |
| `BAD_REQUEST`           | 400         | Used when the request is incorrectly formatted.                          |
| `INTERNAL_SERVER_ERROR` | 500         | Used when there is a server error (likely a bug that needs to be fixed). |

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

### 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.

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

#### Handling user errors

<ul>
  <li>
    User errors do not result in a failed HTTP request. The status will be 200
    OK but the mutation will have no effect.
  </li>

  <li>
    Always check for `userErrors` in the response, especially when calling
    mutations.
  </li>
</ul>

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

## 🏷️ Request ID for debugging

Every 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

<ul>
  <li>
    Log GraphQL and user errors separately — they represent different classes of
    problems.
  </li>

  <li>
    Use GraphQL IDEs (e.g. Insomnia, GraphiQL) to catch schema errors before
    deployment.
  </li>

  <li>
    Always include a Request-Id when reporting issues to
    [developers@ownright.com](mailto:developers@ownright.com).
  </li>
</ul>