demodian_best-practices | Stripe Developers | Page 1

native palmBOT Jul 8, 2025, 5:01 PM

#

👋 Welcome to your new thread!

⏲️ We'll be here soon! Typically we respond in a few minutes, but sometimes we might take a bit longer if the server is busy or if you have a particularly tricky question.

⏱️ We close idle threads, which makes them read-only. Once a thread is closed it won't be reopened, but you can always start a new thread if you have another question.

🔗 This thread will always be available, even after it's closed. You can find it again using Discord's search, or you can save this link: https://discord.com/channels/841573134531821608/1392188770228506654

📝 Have more to share? Add more details, code, screenshots, videos, etc. below.

Below are links to other discussions we've had with you in the past week in case you want to review that information. If your question is related to one of these previous discussions, please provide a comprehensive summary of the current state and what you need help with now. We help many users simultaneously, so a summary allows us to resolve your issue as soon as possible.

demodian_error, 4 days ago, 64 messages

#

golden lagoon Jul 8, 2025, 5:12 PM

#

Hi hi! Can you tell me what version of the SDK you're using?

blissful mason Jul 8, 2025, 5:15 PM

#

15.7.0

native palmBOT Jul 8, 2025, 5:16 PM

#

blissful mason Jul 8, 2025, 5:16 PM

#

I haven't had an opportunity to update to latest and greatest yet

#

probably should, but i've got other major fires on my plate

golden lagoon Jul 8, 2025, 5:22 PM

#

No no, no worries. You shouldn't have to until you're ready (other than security-related things).

#

Have you seen this yet? https://docs.stripe.com/error-handling?lang=php

#

Or more specifically: https://docs.stripe.com/error-handling?lang=php#error-types

blissful mason Jul 8, 2025, 5:30 PM

#

i've seen that, but the SDK has like 21 different exceptions defined (that I've found so far). unless I go through the SDK source and check every class/method, how will I easily know which exceptions to guard against?

#

the structure of the SDK is layered, so how do I know which exceptions to use without a lot of digging?

lapis wharf Jul 8, 2025, 5:36 PM

#

hi! fyi i'm taking over this thread - catching up on a few things but i'll get back to you asap

#

ok, my attention is back here... i think the guide timebox listed is the best source we have on error handling but i can poke around a bit more

blissful mason Jul 8, 2025, 5:43 PM

#

short of checking Google AI to look at different code examples, is there a best-case reference for all exceptions to use and when for the different methods other than the SDK itself?

#

i'm trying to tidy up the code. had to update our production site to match our testing site. the production site was at SDK version 7.x.x so at least it's now ad 15.x.x, but I just want to make sure I at least get the basics updated. I would still have to check everything versus 17.x.x which is latest

native palmBOT Jul 8, 2025, 5:50 PM

#

blissful mason Jul 8, 2025, 5:56 PM

#

for the most part, the major one used is ApiErrorException, but with 20 other exceptions, when are they used? i just want to make sure this wrapper is bulletproof

lapis wharf Jul 8, 2025, 6:02 PM

#

i'm a little less familiar with the PHP SDK, so the exceptions documented in the error handling page are the ones i'm more familiar with. i might need to run this by someone with a little more experience with the PHP SDK specifically, but in the meantime can you share an example exception you've run into that isn't documented on that page?

blissful mason Jul 8, 2025, 6:04 PM

#

as far as I'm aware, this is the full list I've found just looking in the lib/Exception directory:

use Stripe\Exception\ApiConnectionException;
use Stripe\Exception\ApiErrorException;
use Stripe\Exception\AuthenticationException;
use Stripe\Exception\BadMethodCallException;
use Stripe\Exception\CardException;
use Stripe\Exception\IdempotencyException;
use Stripe\Exception\InvalidArgumentException;
use Stripe\Exception\InvalidRequestException;
use Stripe\Exception\OAuth\InvalidClientException.php
use Stripe\Exception\OAuth\InvalidGrantException.php
use Stripe\Exception\OAuth\InvalidRequestException.php
use Stripe\Exception\OAuth\InvalidScopeException.php
use Stripe\Exception\OAuth\OAuthErrorException.php
use Stripe\Exception\OAuth\UnknownOAuthErrorException.php
use Stripe\Exception\OAuth\UnsupportedGrantTypeException.php
use Stripe\Exception\OAuth\UnsupportedResponseTypeException.php
use Stripe\Exception\PermissionException;
use Stripe\Exception\RateLimitException;
use Stripe\Exception\SignatureVerificationException;
use Stripe\Exception\UnexpectedValueException;
use Stripe\Exception\UnknownApiErrorException;

#

just wanting to know if these are all required and how I need to protect against them

lapis wharf Jul 8, 2025, 6:13 PM

#

still digging on this... gimme a bit

blissful mason Jul 8, 2025, 6:16 PM

#

no problem. So far looking in the SDK for all class/methods we use, everything looks like ApiErrorException (except for the case of OAuthErrorException) in the source, but if that's all that's being used, then why are all the others there?

lapis wharf Jul 8, 2025, 6:16 PM

#

yeah that's what i'm trying to figure out too haha

blissful mason Jul 8, 2025, 6:20 PM

#

for example searching the SDK for CardException, i get this:

init.php:require DIR . '/lib/Exception/CardException.php';
lib/ApiRequestor.php: return Exception\CardException::factory($msg, $rcode, $rbody, $resp, $rheaders, $code, $declineCode, $param);
lib/Charge.php: * These strings are applicable to the decline_code property of the \Stripe\Exception\CardException exception.
lib/Exception/CardException.php: * CardException is thrown when a user enters a card that can't be charged for
lib/Exception/CardException.php:class CardException extends ApiErrorException
lib/Exception/CardException.php: * Creates a new CardException exception.
lib/Exception/CardException.php: * @return CardException

looks like the only use is Charge API Requestors?

#

but that's not for any method, but rather a block of consts for the class

#

tells me that the code documentation is possibly lacking for all possible exceptions on methods, since i know that payment intents can be for card transactions, yet there's no reference to CardException in PaymentIntent.php

#

make sense?

#

I hope I'm not starting too much a problem with this issue...

lapis wharf Jul 8, 2025, 6:36 PM

#

haha no, you're fine! i'm juggling a few things at the moment, sorry for being slow

blissful mason Jul 8, 2025, 6:37 PM

#

no worries. I'm working on other code changes while I wait

native palmBOT Jul 8, 2025, 6:44 PM

#

coral fable Jul 8, 2025, 6:50 PM

#

Hello
The exceptions you need to guard against are typically dependent on what sort of integration you're building and what APIs you're using
The ones outlined in the doc here are the recommended ones that apply to most integrations - https://docs.stripe.com/error-handling?lang=php#error-types

However, if you're particularly worried about a specific usecase - you can test your code using various test cards
https://docs.stripe.com/testing and see what sort of exceptions are thrown

blissful mason Jul 8, 2025, 6:53 PM

#

that seems like a bit of a weak response considering the SDK source should be the bible, and I shouldn't have to run through every situation because I don't know what cases apply in every situation. If an exception is possible, it should be listed, right?

#

I really don't have time to figure out the whole SDK with all kinds of random testing and see where things blow up. It should be documented

#

and I have absolutely no control over what the Stripe servers will return as issues

coral fable Jul 8, 2025, 6:59 PM

#

I get that but you do know what API endpoints you're planning to use/using right? If so, you can guard against the relevant ones listed in the docs?

For example, are you integrating a webhook? If so, you would likely run into Stripe\Exception\SignatureVerificationException. Are you using any OAuth based flows? If so, you may need to guard against OAuth specific exceptions.

blissful mason Jul 8, 2025, 7:01 PM

#

I went through the SDK source checking all class/methods I use, and there are only two listed through the SDK, and that's ApiErrorException and OAuthErrorException.

coral fable Jul 8, 2025, 7:04 PM

#

Listed where?

blissful mason Jul 8, 2025, 7:05 PM

#

example, in lib/PaymentIntent.php line 112 for the create() method

#

line 238 for capture() method

#

capture() is when you try to capture the charge for the payment intent, right? there could be issues with a card, if it's a card purchase

#

/**
* @param null|array $params
* @param null|array|string $opts
*
* @return PaymentIntent the captured payment intent
*
* @throws Exception\ApiErrorException if the request fails
*/
public function capture($params = null, $opts = null)
{
$url = $this->instanceUrl() . '/capture';
list($response, $opts) = $this->_request('post', $url, $params, $opts);
$this->refreshFrom($response, $opts);

    return $this;
}

coral fable Jul 8, 2025, 7:08 PM

#

Are you setting capture_method: 'manual' when you create a PaymentIntent?

blissful mason Jul 8, 2025, 7:08 PM

#

yeah, especially with the terminal

coral fable Jul 8, 2025, 7:09 PM

#

If the capture request fails, it will throw ApiErrorException with the appropriate error message

#

I don't believe it raises a CardException

blissful mason Jul 8, 2025, 7:09 PM

#

ever?

#

if ApiErrorException is a catch-all case, then why do the others exist?

coral fable Jul 8, 2025, 7:14 PM

#

I wouldn't say ever.. but it depends on what caused the request to fail.

blissful mason Jul 8, 2025, 7:15 PM

#

in lib/ApiRequestor.php line 218, there's a switch with a lot based on response code, I'm guessing, but that looks like status codes from the server. so when would they be applicable?

#

I remember back in older versions of the SDK, examples would have lots of catch() blocks, and if I didn't have them all, there'd be something that would die in the code. But having huge lists of unnecessary chains of catches is ugly if they are not ever emitted./triggered

#

(and just a heads up, I've got about 20 minutes left before I have to shutdown my computer)

coral fable Jul 8, 2025, 7:27 PM

#

The code in ApiRequestor is lower level afaik. That is something abstracted behind SDK methods.

Pardon my naive understanding of PHP but you could do something like

  catch (Throwable $e){
      call_some_generic_function_to_handle($e);
  }

and catch all exceptions right? Inside there, you could check for these types: https://docs.stripe.com/error-handling?lang=php#error-types and if it's not one of these, maybe set off an alert?

blissful mason Jul 8, 2025, 7:29 PM

#

<?php
require 'vendor/autoload.php';
\Stripe\Stripe::setApiKey('sk_test_BQokikJOvBiI2HlWgH4olfQ2');

this is the example code in the page for php error handling, yet ApiErrorException is not used. would it failover to Exception or does it have to be specifically listed?

coral fable Jul 8, 2025, 7:30 PM

#

It would be caught by the Exception line, yes

blissful mason Jul 8, 2025, 7:34 PM

#

because my diff of an affected code is this:

            try {
                    Account::retrieve($token, []);
                    return Payment::SUCCESS;

```
          } catch(Exception $e) {
```

          } catch(ApiErrorException $e) {
                  Payment::set_error("Account connection revoked - check failed for {$eventid}");
                  return Payment::ERROR;
          }

and it failed to capture the general exception

#

that was the error I dealt with this morning

#

yes, I had a bad value for token, but the catch(Exception $e) did not catch the error

coral fable Jul 8, 2025, 7:37 PM

#

It should've as far as I know unless it was caught earlier in the chain

blissful mason Jul 8, 2025, 7:40 PM

#

there was nothing else in the chain as I could tell. that was the perplexing part. the original code was just the Exception. the code now reads ApiErrorException.

#

[08-Jul-2025 11:19:30 America/Chicago] PHP Fatal error: Uncaught Error sending request to Stripe: (Status 403) The provided key 'sk_test_***********************************************************************************************Dy0s' does not have access to account 'Stripe' (or that account does not exist). Application access may have been revoked.
Stripe\Exception\PermissionException: The provided key 'sk_test_***********************************************************************************************Dy0s' does not have access to account 'Stripe' (or that account does not exist). Application access may have been revoked. in /mtp/inc/payments/stripe-php-master/lib/Exception/ApiErrorException.php:38
Stack trace:
#0 /mtp/inc/payments/stripe-php-master/lib/ApiRequestor.php(234): Stripe\Exception\ApiErrorException::factory()
#1 /mtp/inc/payments/stripe-php-master/lib/ApiRequestor.php(187): Stripe\ApiRequestor::_specificAPIError()
#2 /mtp/inc/payments/stripe-php-master/lib/ApiRequestor.php(577): Stripe\ApiRequestor->handleErrorResponse()
#3 /mtp/inc/payments/str in /mtp/inc/payments/stripe-php-master/lib/Exception/ApiErrorException.php on line 38

#

that was my error log this mornign

#

the account 'Stripe' was my fault, but the general exception was NOT caught

coral fable Jul 8, 2025, 7:41 PM

#

What version of PHP are you running?

blissful mason Jul 8, 2025, 7:42 PM

#

it's 7.4 on this server

#

it's 20.04 Ubuntu, and that will need to be updated, but we'd need another machine to get to a newer OS version and php

coral fable Jul 8, 2025, 7:43 PM

#

You could try with catch (Throwable $e) and re-test with the same API request

#

I believe Throwable is supported in PHP 7+

native palmBOT Jul 8, 2025, 7:44 PM

#

blissful mason Jul 8, 2025, 7:47 PM

#

it is, but that's a very last ditch thing to look for.. and i'm going to have to shutdown

#

On my phone for now

safe sphinx Jul 8, 2025, 7:49 PM

#

What does 'and i'm going to have to shutdown' mean?

blissful mason Jul 8, 2025, 7:51 PM

#

My laptop. Changing my location

#

(At dialysis, and my session is finishing)

safe sphinx Jul 8, 2025, 7:56 PM

#

I see, please take care of yourself. We will be here

blissful mason Jul 8, 2025, 7:57 PM

#

The example on the error handling page just lists Exception, which was available in 7.4, but it failed as a fallback

safe sphinx Jul 8, 2025, 8:00 PM

#

There are a ton of back and forth here. Can you summary the latest question for me please?

blissful mason Jul 8, 2025, 8:03 PM

#

Shouldn't the SDK source document all of the possible exceptions for each method? Everything is basically just ApiErrorException for what I use in the method documentation in the source

#

(Typing will be tough for the next few minutes)

safe sphinx Jul 8, 2025, 8:15 PM

#

We document some of the exceptions here: https://docs.stripe.com/error-handling?lang=php#error-types and recommendations on error handling here: https://docs.stripe.com/error-handling

#

I can share your feedback to document all the possible exceptions for each method to the owning team for product reiterations.

blissful mason Jul 8, 2025, 8:17 PM

#

Some but not exhaustive. A general purpose Exception fail to catch it

#

Not sure if that's a problem with php 7.4, but it's my situation this morning

safe sphinx Jul 8, 2025, 8:31 PM

#

To ensure we're on the same page, are you saying that the general purpose Exception did not capture ApiErrorException?

blissful mason Jul 8, 2025, 8:32 PM

#

Yes

safe sphinx Jul 8, 2025, 8:40 PM

#

We document that exception: https://docs.stripe.com/error-handling?lang=php#error-types and document how you can respond to it here: https://docs.stripe.com/error-handling?lang=php#api-errors . Let me ask a teammate who has more PHP experience to confirm something, hang tight

blissful mason Jul 8, 2025, 8:40 PM

#

Sure

native palmBOT Jul 8, 2025, 8:46 PM

#

summer iron Jul 8, 2025, 8:49 PM

#

👋 do you have a clear basic end-to-end PHP script that reproduces the error?

blissful mason Jul 8, 2025, 8:50 PM

#

back on laptop. I can get one put together in a few minutes

summer iron Jul 8, 2025, 8:50 PM

#

Thanks I think it will help align versus a meta discussion about what might happen

blissful mason Jul 8, 2025, 8:57 PM

#

this is basically the code as it was this morning

📎 stripeexcerpt.php

summer iron Jul 8, 2025, 8:57 PM

#

Here's my basic repro script:


error_reporting(E_ALL);
ini_set('display_errors', 1);

require_once('vendor/autoload.php');

$stripe = new \Stripe\StripeClient([
  'api_key' => 'sk_test_BQokikJOvBiI2HlWgH4olfQ2',
]);

try {
  echo "Trying to create a Payout<br>";
  $payout = $stripe->payouts->create([
      'amount' => 100,
      'currency' => 'eur',
  ]);
  echo "succeeded!<br>";
} catch(\Stripe\Exception\CardException $e) {
  error_log("A CardException occurred");
  echo "A CardException occurred: " .$e->getError()->message . " - Request id: " . $e->getRequestId();
} catch (\Stripe\Exception\InvalidRequestException $e) {
  error_log("An InvalidRequestException occurred");
  echo "An InvalidRequestException occurred: " .$e->getError()->message . " - Request id: " . $e->getRequestId();
} catch (\Stripe\Exception\ApiErrorException $e) {
  error_log("A generic Stripe ApiErrorException occurred");
  echo "A generic Stripe Exception occurred: " .$e->getError()->message . " - Request id: " . $e->getRequestId();
}catch (Exception $e) {
  echo "an error occurred that isn't Stripe";
}```

This will fail in the second catch with `InvalidRequestException` because it's a 400. If you remove that one it then ends up in the next one. And if you remove that one it ends up in Exception

blissful mason Jul 8, 2025, 8:58 PM

#

sorry, yeah, needs the other things at the top

summer iron Jul 8, 2025, 8:59 PM

#

Can you try mine first and confirm the behaviour? Yours is a bit less straightforward with your import and not using the \Stripe paths

blissful mason Jul 8, 2025, 9:26 PM

#

it's working with the example (but all specific exceptions commented out) I even made it similar to my style (e.g. Account::retrieve()) and the example is okay. this is weird

golden lagoon Jul 8, 2025, 9:28 PM

#

Hi again! In that case, the issue must be happening elsewhere in your code.

blissful mason Jul 8, 2025, 9:31 PM

#

i'm checking for Exception to see if it is defined somewhere else, but the error message was specifically Stripe-related

#

i can run the old code on our beta site and it is still doing it because it hasn't been updated yet

summer iron Jul 8, 2025, 9:37 PM

#

I wonder if it is to do with your use Stripe\Account; use Stripe\Stripe;

#

I'm a PHP developer in theory but I learnt all of my craft before namespaces were introduced 😂
I feel like this is kinda catching the "wrong" exception. Maybe try catch (\Exception $e)?

blissful mason Jul 8, 2025, 9:39 PM

#

that's valid PHP though... moment

#

damn, that did it. okay, i feel like an idiot -_-

#

thank you

#

(though to be exact, knowing when to handle specific exceptions would be important, so updated documentation would be helpful depending on the actions that have to be taken)

summer iron Jul 8, 2025, 9:52 PM

#

I get your feedback though I feel like https://docs.stripe.com/error-handling?lang=php is quite clear already. I am biased though I pushed hard to get that doc out a couple years ago 🙂

#

In most cases you'd handle all Stripe exceptions the same other than the card decline one which I would special-case

blissful mason Jul 8, 2025, 9:53 PM

#

the code that was failing for this was in a namespace, so maybe have it listed as \Exception in the example?

#

just to be explicit, because i'm sure no one actually puts all their Stripe code in a public web root

summer iron Jul 8, 2025, 9:55 PM

#

I mean web root and namespacing are unrelated

#

the example already uses \Stripe\ which makes it explicit in which case Exception is correct. It's when you change the namespacing that it doesn't work.

#

I'll flag but I'm dubious we'd write \Exception just to catch that use-case though you aren't the first one hitting this (which is why I offered that alternative from some previous convos) so maybe it'd still help

blissful mason Jul 8, 2025, 9:56 PM

#

please

golden lagoon Jul 8, 2025, 9:57 PM

#

lurk, but ...I'm pretty sure we're referencing this builtin: https://www.php.net/manual/en/class.exception.php

blissful mason Jul 8, 2025, 9:57 PM

#

(this is a custom framework, and i didn't have a use \Exception; so yeah... -_-)

summer iron Jul 8, 2025, 9:57 PM

#

@golden lagoon sure that part we were aligned on

blissful mason Jul 8, 2025, 9:58 PM

#

anyhow, thank you all for your patience

summer iron Jul 8, 2025, 10:01 PM

#

sure thing!

#demodian_best-practices