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.

{
  "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:

{
  "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:

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

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.

Getting Started

Guides

API Reference

Error response format

Error codes

Handling errors in your integration

Authentication errors

Access errors

Not found errors

Internal errors

​Error response format

​Error codes

​Handling errors in your integration

​Authentication errors

​Access errors

​Not found errors

​Internal errors

Error response format

Error codes

Handling errors in your integration

Authentication errors

Access errors

Not found errors

Internal errors