​
Authentication Error Codes

The API returns specific error codes when authentication-related issues occur. These codes help identify the exact nature of the problem so that you can take appropriate action.

Error CodeDescription
ERR_UNAUTHORIZEDGeneral authentication failure. This error occurs when your request lacks valid authentication credentials or the provided credentials are invalid. Check that you’re including your API key in the x-believe-api-key header and that the key is active.
ERR_DUPLICATE_IDEMPOTENCY_KEYA request with the same X-Idempotency-Key header value has already been processed successfully. This prevents duplicate operations. If you receive this error, it means your original request was successful, and you should retrieve the original response rather than retrying with the same idempotency key.
ERR_KEY_SCOPES_UNAUTHORIZEDThe API key used for the request doesn’t have the required scope permissions for the requested operation. For example, a key without the burn scope cannot access the /v1/tokenomics/burn endpoint. Check your API key’s scope assignments and request the appropriate scopes for your intended operations.

​
Response Format

When an authentication error occurs, the API returns a 4xx HTTP status code along with a JSON response containing the error code and a descriptive message.

Example:

{
  "error": "ERR_KEY_SCOPES_UNAUTHORIZED",
  "message": "The provided API key doesn't have the required 'burn' scope to access this endpoint"
}