Skip to main content

​
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

CodeHTTP StatusDescription
NOT_AUTHENTICATED401Missing or invalid API key in the Authorization header.
NO_APIKEY401No Authorization header was provided.
USER_NOT_FOUND404The API key does not match any registered integration.
METHOD_NOT_ALLOWED405Your API key does not have access to the requested query or mutation.
LOCATION_NOT_ALLOWED403The request originates from an IP address not in your allowlist.
NOT_FOUND404The requested resource does not exist.
FAMILY_NOT_FOUND404The requested fragrance family was not found.
PERFUMIST_NOT_FOUND404The requested perfumist was not found.
INTERNAL_SERVER_ERROR500An 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.
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.