api: detect and report lingering idempotency keys (#204)

Stripe Idemptency Keys linger after a Test Mode data purge, causing
false positive responses from Stripe. One such scenario is creating a
customer using a deterministic Idempotency Key with a Tier orgID (e.g.
"create:customer:org:example") to suppress a duplicate request from a
dueling client. If after that key is created, and our Test Mode is
purged, we'll get a cached response back from Stripe telling us the
customer was created and give us the old response without actually
creating the customer in the now clean Test Mode. Using that customer ID
to create a subscription resulted in a "resource_not_found" error from
Stripe because the customer did not exist.

Tier now detects an error resulting from a lingering idempotency key
when creating a schedule for a customer that was thought to be created
just before attempting to create the schedule. The output should now be
more helpful.

This commit also introduces the new error code scheme with an error code
prefixed with ("TERR"). It is pronounced, "terror". Moving forward, all
new errors will have a TERR-code. This makes specific errors easier to
report and search for.

api/api.go

@@ -29,6 +29,11 @@ var errorLookup = map[error]error{
 		Code:    "feature_not_found",
 		Message: "feature not found",
 	},
+	control.ErrUnexpectedMissingOrg: &trweb.HTTPError{
+		Status:  500,
+		Code:    "TERR1050",
+		Message: "Stripe reported a customer was created and then reported it did not exist. This might mean you purged your Test Mode and need to reset TIER_PREFIX_KEY=<randomString>.",
+	},
 	control.ErrFeatureNotMetered: &trweb.HTTPError{ // TODO(bmizerany): this may be relaxed if we decide to log and accept
 		Status:  400,
 		Code:    "invalid_request",

cmd/tier/tier_test.go

@@ -491,6 +491,65 @@ func TestSubscribe(t *testing.T) {
 	tt.GrepBothNot(".+", "unexpected output")
 }
 
+const responsePricesValidPlan = `
+	{
+	  "object": "list",
+	  "url": "/v1/prices",
+	  "has_more": false,
+	  "data": [
+	    {
+	      "id": "price_1MG5iBCdYGloJaDMbVbTZlN1",
+	      "object": "price",
+	      "active": true,
+	      "billing_scheme": "per_unit",
+	      "created": 1671303979,
+	      "currency": "usd",
+	      "custom_unit_amount": null,
+	      "livemode": false,
+	      "lookup_key": null,
+	      "metadata": {
+		"tier.plan": "plan:foo@0",
+		"tier.feature": "feature:bar@plan:foo@0"
+	      },
+	      "nickname": null,
+	      "product": "tier__feature-phone-number-plan-basic-7",
+	      "recurring": {
+		"aggregate_usage": null,
+		"interval": "month",
+		"interval_count": 1,
+		"usage_type": "licensed"
+	      },
+	      "tax_behavior": "unspecified",
+	      "tiers_mode": null,
+	      "transform_quantity": null,
+	      "type": "recurring",
+	      "unit_amount": 2000,
+	      "unit_amount_decimal": "2000"
+	    }
+	  ]
+	}
+`
+
+func TestSubscribeUnexpectedMissingCustomer(t *testing.T) {
+	tt := testtier(t, func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path == "/v1/subscription_schedules" {
+			w.WriteHeader(400)
+			io.WriteString(w, `{
+				"error": {
+					"code": "resource_missing",
+					"param": "customer"
+				}
+			}`)
+		} else if r.URL.Path == "/v1/prices" {
+			io.WriteString(w, responsePricesValidPlan)
+		} else {
+			io.WriteString(w, `{}`)
+		}
+	})
+	tt.RunFail("subscribe", "org:test", "plan:foo@0")
+	tt.GrepStderr("TERR1050", "expected customer not found")
+}
+
 func chdir(t *testing.T, dir string) {
 	dir0, err := os.Getwd()
 	if err != nil {

control/schedule.go

@@ -26,6 +26,12 @@ var (
 	ErrOrgNotFound     = errors.New("org not found")
 	ErrInvalidMetadata = errors.New("invalid metadata")
 	ErrInvalidPhase    = errors.New("invalid phase")
+
+	// ErrInvalidFeature is returned when a customer that should have been
+	// created is not found after "creating" it. This can happen in Test
+	// Mode if the test data was cleared but the idempotency key is still
+	// cached at Stripe.
+	ErrUnexpectedMissingOrg = errors.New("unexpected missing org")
 )
 
 type ValidationError struct {
@@ -239,8 +245,13 @@ func (c *Client) updateSchedule(ctx context.Context, id, name string, phases []P
 func (c *Client) Schedule(ctx context.Context, org string, info *OrgInfo, phases []Phase) (err error) {
 	err = c.schedule(ctx, org, info, phases)
 	var e *stripe.Error
-	if errors.As(err, &e) && strings.Contains(e.Message, "maximum number of items") {
-		return ErrTooManyItems
+	if errors.As(err, &e) {
+		if e.Code == "resource_missing" && e.Param == "customer" {
+			return ErrUnexpectedMissingOrg
+		}
+		if strings.Contains(e.Message, "maximum number of items") {
+			return ErrTooManyItems
+		}
 	}
 	return err
 }