Add error messages to benefit grants

[frankie567]

In some cases, we might have unrecoverable errors when trying to grant a benefit.

Typically, with the GitHub benefit, we had a case where the organization didn't have any seat left to invite the customer. This is unrecoverable for us, but we need to inform the customer about it.

We have the BenefitActionRequiredError exception raised in this kind of cases, but we do nothing from it.

What we could do is to add a dedicated (JSONB?) column to store the error information, so we can display it properly in the UI.

[psincraian]

Hey,

I would like to work on the problem. My plan is to do the following:

PR1: Store the error message

1. Add a new JSONB column in the BenefitGrant class that stores the error information like:

{
  "message": "The organization doesn't have any seats left to invite the customer",
  "type": "BenefitActionRequiredError",
  "timestamp": "2025-05-15T14:30:00.000Z"
}

2. Create the migration to add the new column
3. Modify the BenefitGrantBase to expose the new field in the API.
4. Modify the BenefitGrantService in the relevant methods to handle the new use case.
5. Modify the tests

PR2: Make the changes in the frontend to display the error information

Pending to analyze and define the steps.

[psincraian]

I’m setting up my local environment to test the integration. I followed the Polar guide and created a small Next.js app with a basic checkout flow.

However, when I try to complete a checkout, I get stuck on this page:

After checking the flow:

• The payment appears successful in my Stripe sandbox.
• The customer is correctly created in Polar.
• But then it seems to get stuck…

Looking into it, I see an error when receiving the webhook from Stripe, it looks like a required property is missing 🤔.

Any idea on how to fix it?

2025-05-15T15:15:30.426095Z [debug    ] Received message stripe.webhook.payment_intent.succeeded('6a20f772-39e2-47e6-a88b-ac4fad10d1d8') with id 'c01bdbc8-34c8-4998-ae03-9f2470efe4a4'. [dramatiq.worker.WorkerThread]
2025-05-15 17:15:30,427 INFO sqlalchemy.engine.Engine BEGIN (implicit)
2025-05-15T15:15:30.427901Z [info     ] BEGIN (implicit)               [sqlalchemy.engine.Engine] asctime='2025-05-15 17:15:30,427' message='BEGIN (implicit)'
2025-05-15 17:15:30,429 INFO sqlalchemy.engine.Engine SELECT external_events.source, external_events.handled_at, external_events.task_name, external_events.external_id, external_events.data, external_events.id, external_events.created_at, external_events.modified_at, external_events.deleted_at 
FROM external_events 
WHERE external_events.source = $1::VARCHAR AND external_events.id = $2::UUID
2025-05-15T15:15:30.429659Z [info     ] SELECT external_events.source, external_events.handled_at, external_events.task_name, external_events.external_id, external_events.data, external_events.id, external_events.created_at, external_events.modified_at, external_events.deleted_at 
FROM external_events 
WHERE external_events.source = $1::VARCHAR AND external_events.id = $2::UUID [sqlalchemy.engine.Engine] asctime='2025-05-15 17:15:30,429' message='SELECT external_events.source, external_events.handled_at, external_events.task_name, external_events.external_id, external_events.data, external_events.id, external_events.created_at, external_events.modified_at, external_events.deleted_at \nFROM external_events \nWHERE external_events.source = $1::VARCHAR AND external_events.id = $2::UUID'
2025-05-15 17:15:30,430 INFO sqlalchemy.engine.Engine [generated in 0.00075s] ('stripe', '6a20f772-39e2-47e6-a88b-ac4fad10d1d8')
2025-05-15T15:15:30.430183Z [info     ] [generated in 0.00075s] ('stripe', '6a20f772-39e2-47e6-a88b-ac4fad10d1d8') [sqlalchemy.engine.Engine] asctime='2025-05-15 17:15:30,430' message="[generated in 0.00075s] ('stripe', '6a20f772-39e2-47e6-a88b-ac4fad10d1d8')"
2025-05-15 17:15:30,437 INFO sqlalchemy.engine.Engine ROLLBACK
2025-05-15T15:15:30.438023Z [info     ] ROLLBACK                       [sqlalchemy.engine.Engine] asctime='2025-05-15 17:15:30,437' message=ROLLBACK
/Volumes/workplace/personal/polar/server/.venv/lib/python3.12/site-packages/structlog/stdlib.py:1148: UserWarning: Remove `format_exc_info` from your processor chain if you want pretty exceptions.
  ed = p(logger, meth_name, cast(EventDict, ed))
2025-05-15T15:15:30.441619Z [error    ] Failed to process message stripe.webhook.payment_intent.succeeded('6a20f772-39e2-47e6-a88b-ac4fad10d1d8') with unhandled exception. [dramatiq.worker.WorkerThread]
Traceback (most recent call last):
  File "/Volumes/workplace/personal/polar/server/.venv/lib/python3.12/site-packages/dramatiq/worker.py", line 487, in process_message
    res = actor(*message.args, **message.kwargs)
          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Volumes/workplace/personal/polar/server/.venv/lib/python3.12/site-packages/dramatiq/actor.py", line 185, in __call__
    return self.fn(*args, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Volumes/workplace/personal/polar/server/.venv/lib/python3.12/site-packages/dramatiq/asyncio.py", line 67, in wrapper
    return event_loop_thread.run_coroutine(async_fn(*args, **kwargs))
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Volumes/workplace/personal/polar/server/.venv/lib/python3.12/site-packages/dramatiq/asyncio.py", line 147, in run_coroutine
    return future.result(timeout=self.interrupt_check_ival)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/petru/.pyenv/versions/3.12.7/lib/python3.12/concurrent/futures/_base.py", line 456, in result
    return self.__get_result()
           ^^^^^^^^^^^^^^^^^^^
  File "/Users/petru/.pyenv/versions/3.12.7/lib/python3.12/concurrent/futures/_base.py", line 401, in __get_result
    raise self._exception
  File "/Volumes/workplace/personal/polar/server/.venv/lib/python3.12/site-packages/dramatiq/asyncio.py", line 137, in wrapped_coro
    return await coro
           ^^^^^^^^^^
  File "/Volumes/workplace/personal/polar/server/polar/integrations/stripe/tasks.py", line 63, in wrapper
    return await func(*args, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Volumes/workplace/personal/polar/server/polar/integrations/stripe/tasks.py", line 107, in payment_intent_succeeded
    payload = PaymentIntentSuccessWebhook.model_validate(payment_intent)
              ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Volumes/workplace/personal/polar/server/.venv/lib/python3.12/site-packages/pydantic/main.py", line 627, in model_validate
    return cls.__pydantic_validator__.validate_python(
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
pydantic_core._pydantic_core.ValidationError: 1 validation error for PaymentIntentSuccessWebhook
invoice
  Field required [type=missing, input_value=<PaymentIntent payment_in..."transfer_group": null
}, input_type=PaymentIntent]
    For further information visit https://errors.pydantic.dev/2.10/v/missing

[psincraian]

@frankie567 I just created my first attempt to address the issue. Please take a look #5705

[frankie567]

Hi @psincraian 👋 Thank you for your interest!

PR1: Store the error message

Looks like a good plan! I'll review the PR 👍

Looking into it, I see an error when receiving the webhook from Stripe, it looks like a required property is missing 🤔.

Weird! At first glance, I would say it's because of a setting in your Stripe sandbox. Invoices are part of their "Billing" features, so you should check if it's enabled in your Stripe settings. I think you can find that here:

• https://dashboard.stripe.com/billing/starter-guide
• https://dashboard.stripe.com/settings/billing/automatic

[psincraian]

I just noticed there’s a customer-facing page that displays the grants. I would suggest updating CustomerGrantBenefit to include only a new boolean attribute is_errored. Since this is exposed to customers, I don’t think it’s useful to show detailed error info, they would reach out to the owner.

What do you think?

In any case, I prefer to keep this PR small and focused, so I’ll open a separate one for that change later.

[frankie567]

I just noticed there’s a customer-facing page that displays the grants. I would suggest updating CustomerGrantBenefit to include only a new boolean attribute is_errored. Since this is exposed to customers, I don’t think it’s useful to show detailed error info, they would reach out to the owner.

What do you think?

In any case, I prefer to keep this PR small and focused, so I’ll open a separate one for that change later.

Very good point, 100% agree. The customer should only see a generic error message.

[frankie567]

Looking into it, I see an error when receiving the webhook from Stripe, it looks like a required property is missing 🤔.

Tried to upgrade our dependencies, including Stripe SDK and stumbled upon lot of breaking changes in their latest API version, including depreciation of invoice field in lot of places (FML 😩). So that's probably the problem here.

If you configure your Stripe account to use the version 2025-02-24.acacia; it should work.

[psincraian]

I will take a look at this once I'm back from holidays. Thanks for the guidance @frankie567