The subject_token provided is invalid

I have an intermittent problem where the Python Box SDK is raising the following exception when generating a down scoped token. The code works most of the time but occasionally will stop working for a few minutes. Do the JWT tokens need to be expired or released? The code is being run from an AWS Lambda and the downscoped token only needs to be used once. Is there API rate limit. I don’t think I’m near it usage would be less then 30 an hour but maybe multiple in quick succession. Our Box Account is Business Plus.

boxsdk.exception.BoxAPIException: Message: The subject_token provided is invalid

The code that is generating the error is in the used to create a downscoped token that can be used by a Box Preview embed:

config = JWTAuth.from_settings_file('cert/abcd_1234_config.json')
client = Client(config)
target_file = client.file(file_id=file_id)
token_info = client.downscope_token(['item_preview', 'annotation_view_all', 'annotation_edit'], target_file)

Full Error Trace

Traceback (most recent call last):
  File "/var/task/flask/", line 2073, in wsgi_app
    response = self.full_dispatch_request()
  File "/var/task/flask/", line 1519, in full_dispatch_request
    rv = self.handle_user_exception(e)
  File "/var/task/flask/", line 1517, in full_dispatch_request
    rv = self.dispatch_request()
  File "/var/task/flask/", line 1503, in dispatch_request
    return self.ensure_sync(self.view_functions[rule.endpoint])(**req.view_args)
  File "/var/task/", line 56, in artwork_info
    downscoped_token = get_box_downscoped_preview_token(file_id)
  File "/var/task/", line 73, in get_box_downscoped_preview_token
    token_info = client.downscope_token(['item_preview', 'annotation_view_all', 'annotation_edit'], target_file)
  File "/var/task/boxsdk/util/", line 63, in call
    return method(*args, **kwargs)
  File "/var/task/boxsdk/client/", line 1247, in downscope_token
    box_response =, data=data)
  File "/var/task/boxsdk/session/", line 100, in post
    return self.request('POST', url, **kwargs)
  File "/var/task/boxsdk/session/", line 138, in request
    response = self._prepare_and_send_request(method, url, **kwargs)
  File "/var/task/boxsdk/session/", line 375, in _prepare_and_send_request
    self._raise_on_unsuccessful_request(network_response, request, raised_exception)
  File "/var/task/boxsdk/session/", line 271, in _raise_on_unsuccessful_request
    raise BoxAPIException(
boxsdk.exception.BoxAPIException: Message: The subject_token provided is invalid
Status: 400
Code: invalid_request
Request ID: None
Headers: {'Date': 'Tue, 06 Feb 2024 03:23:20 GMT', 'Content-Type': 'application/json', 'Strict-Transport-Security': 'max-age=31536000', 'Set-Cookie': 'box_visitor_id=65c1a628174fe4.21384767; expires=Thu, 06-Feb-2025 03:23:20 GMT; Max-Age=31622400; path=/;; secure; SameSite=None, bv=MONO-5788; expires=Tue, 13-Feb-2024 03:23:20 GMT; Max-Age=604800; path=/;; secure, cn=45; expires=Thu, 06-Feb-2025 03:23:20 GMT; Max-Age=31622400; path=/;; secure, site_preference=desktop; path=/;; secure', 'Cache-Control': 'no-store', 'Via': '1.1 google', 'Alt-Svc': 'h3=":443"; ma=2592000,h3-29=":443"; ma=2592000', 'Transfer-Encoding': 'chunked'}
Method: POST
Context Info: None

Hello! :raised_hand:,

Appreciate you posting on the forum! From first glance, the code looks correct. And, based on the error message, it looks like it isn’t the code but maybe the service being called from the code. Would it be possible to add some retry logic if you get that error? Could you also estimate how often it is happening? Like once in a blue moon or all the time?

I would not think its rate limits either.

I’m assuming the error is happing on the .downscope_token(…) line?

In the meantime, let me chat with our python sdk team and see if they have further thoughts.

Alex, Box Developer Advocate :avocado:

Thanks for the response Alex

I’ll add in some retry code. It’s not automated retry code but I know our users have been hitting refresh so manually retrying and this doesn’t clear the problem. Leaving it for 10 minutes to an hour seems to do the job.

I didn’t come across the problem in development or testing which is why I felt it had something to do with rates or frequency.

At the moment it’s happening 1 to 2 times a day. Based on traffic of 10 - 30 views. I’ll build out more detailed logging. If it helps here’s a link to what the end product looks like.

I’m going to send you a pm!