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

# Error Handling

## Error response format

The WikiParfum API returns errors following the standard GraphQL error format. Every error response includes a `message` and an `extensions` object with a machine-readable `code`.

```json theme={null}
{
  "errors": [
    {
      "message": "NOT_AUTHENTICATED",
      "extensions": {
        "code": "NOT_AUTHENTICATED"
      }
    }
  ]
}
```

When a query partially succeeds, the `data` field contains `null` for the failed field alongside the error:

```json theme={null}
{
  "errors": [
    {
      "message": "Internal server error",
      "extensions": {
        "code": "INTERNAL_SERVER_ERROR"
      }
    }
  ],
  "data": {
    "recommendedPerfumes": null
  }
}
```

## Error codes

| Code                    | HTTP Status | Description                                                           |
| ----------------------- | ----------- | --------------------------------------------------------------------- |
| `NOT_AUTHENTICATED`     | 401         | Missing or invalid API key in the `Authorization` header.             |
| `NO_APIKEY`             | 401         | No `Authorization` header was provided.                               |
| `USER_NOT_FOUND`        | 404         | The API key does not match any registered integration.                |
| `METHOD_NOT_ALLOWED`    | 405         | Your API key does not have access to the requested query or mutation. |
| `LOCATION_NOT_ALLOWED`  | 403         | The request originates from an IP address not in your allowlist.      |
| `NOT_FOUND`             | 404         | The requested resource does not exist.                                |
| `FAMILY_NOT_FOUND`      | 404         | The requested fragrance family was not found.                         |
| `PERFUMIST_NOT_FOUND`   | 404         | The requested perfumist was not found.                                |
| `INTERNAL_SERVER_ERROR` | 500         | An unexpected error occurred on the server.                           |

## Handling errors in your integration

### Authentication errors

If you receive `NOT_AUTHENTICATED` or `NO_APIKEY`, verify that:

* The `Authorization` header is present in every request.
* The API key is correct and has not been rotated.
* The request is made server-side (client-side requests are not allowed).

### Access errors

If you receive `LOCATION_NOT_ALLOWED`, the request is coming from an IP address not in your allowlist. Contact your ScentXP account manager to update the allowed IP addresses.

If you receive `METHOD_NOT_ALLOWED`, your API key does not have permission to execute the requested query. Contact your ScentXP account manager to review your access configuration.

### Not found errors

Codes like `FAMILY_NOT_FOUND` or `PERFUMIST_NOT_FOUND` indicate that the requested entity does not exist. Verify that the ID or slug you are using is correct.

### Internal errors

`INTERNAL_SERVER_ERROR` indicates an unexpected issue on the server side. These errors do not expose internal details for security reasons. If you encounter persistent internal errors:

1. Verify that your query syntax and arguments are valid.
2. Retry the request after a short delay.
3. If the issue persists, contact ScentXP support with the query you are executing and the approximate timestamp.

<Note>
  The API never exposes internal implementation details (such as database errors or stack traces) in error responses. Full error details are logged server-side for debugging by the ScentXP team.
</Note>