From 41885e846d3a055496d8e1186c5f946fc4ae2c1d Mon Sep 17 00:00:00 2001 From: Jeremy Date: Thu, 30 Jul 2026 06:26:02 +0000 Subject: [PATCH 1/2] feat: document BENEFICIARY_TRUSTED (409) on customer external-account delete --- mintlify/openapi.yaml | 12 +++++++++++- openapi.yaml | 12 +++++++++++- openapi/components/schemas/errors/Error409.yaml | 2 ++ ...rs_external_accounts_{externalAccountId}.yaml | 16 +++++++++++++++- 4 files changed, 39 insertions(+), 3 deletions(-) diff --git a/mintlify/openapi.yaml b/mintlify/openapi.yaml index d13da97fd..412aae1c1 100644 --- a/mintlify/openapi.yaml +++ b/mintlify/openapi.yaml @@ -2361,7 +2361,9 @@ paths: $ref: '#/components/schemas/Error500' delete: summary: Delete customer external account by ID - description: Delete a customer external account by its system-generated ID + description: |- + Delete a customer external account by its system-generated ID. + An account that is currently a trusted beneficiary cannot be deleted — untrust it first via `POST /customers/external-accounts/{externalAccountId}/untrust` (and its `/confirm`), then delete. operationId: deleteCustomerExternalAccountById tags: - External Accounts @@ -2382,6 +2384,12 @@ paths: application/json: schema: $ref: '#/components/schemas/Error404' + '409': + description: Returned with `BENEFICIARY_TRUSTED` when the external account is currently a trusted beneficiary. Untrust it first, then delete. + content: + application/json: + schema: + $ref: '#/components/schemas/Error409' '500': description: Internal service error content: @@ -12602,6 +12610,7 @@ components: | EMAIL_OTP_CREDENTIAL_SET_CHANGED | Tied EMAIL_OTP credential set changed after the signed-retry challenge was issued | | PASSKEY_ALREADY_ENROLLED | The customer already has an enrolled passkey factor; only one passkey per customer is supported. Delete the existing one before enrolling another | | SCA_SESSION_REQUIRED | The customer's Strong Customer Authentication login session is missing or expired. Re-authenticate the customer, then retry the request. Distinct from a `401`, which means the platform's own API credentials were rejected | + | BENEFICIARY_TRUSTED | The external account is currently a trusted beneficiary, so it cannot be deleted. Untrust it first via `POST /customers/external-accounts/{externalAccountId}/untrust` (and its `/confirm`), then delete | | CONFLICT | Generic resource-state conflict. Returned, for example, when `platformCustomerId` on a customer create call collides with an existing active customer on the same platform | enum: - TRANSACTION_NOT_PENDING_PLATFORM_APPROVAL @@ -12611,6 +12620,7 @@ components: - EMAIL_OTP_CREDENTIAL_SET_CHANGED - PASSKEY_ALREADY_ENROLLED - SCA_SESSION_REQUIRED + - BENEFICIARY_TRUSTED - CONFLICT message: type: string diff --git a/openapi.yaml b/openapi.yaml index d13da97fd..412aae1c1 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -2361,7 +2361,9 @@ paths: $ref: '#/components/schemas/Error500' delete: summary: Delete customer external account by ID - description: Delete a customer external account by its system-generated ID + description: |- + Delete a customer external account by its system-generated ID. + An account that is currently a trusted beneficiary cannot be deleted — untrust it first via `POST /customers/external-accounts/{externalAccountId}/untrust` (and its `/confirm`), then delete. operationId: deleteCustomerExternalAccountById tags: - External Accounts @@ -2382,6 +2384,12 @@ paths: application/json: schema: $ref: '#/components/schemas/Error404' + '409': + description: Returned with `BENEFICIARY_TRUSTED` when the external account is currently a trusted beneficiary. Untrust it first, then delete. + content: + application/json: + schema: + $ref: '#/components/schemas/Error409' '500': description: Internal service error content: @@ -12602,6 +12610,7 @@ components: | EMAIL_OTP_CREDENTIAL_SET_CHANGED | Tied EMAIL_OTP credential set changed after the signed-retry challenge was issued | | PASSKEY_ALREADY_ENROLLED | The customer already has an enrolled passkey factor; only one passkey per customer is supported. Delete the existing one before enrolling another | | SCA_SESSION_REQUIRED | The customer's Strong Customer Authentication login session is missing or expired. Re-authenticate the customer, then retry the request. Distinct from a `401`, which means the platform's own API credentials were rejected | + | BENEFICIARY_TRUSTED | The external account is currently a trusted beneficiary, so it cannot be deleted. Untrust it first via `POST /customers/external-accounts/{externalAccountId}/untrust` (and its `/confirm`), then delete | | CONFLICT | Generic resource-state conflict. Returned, for example, when `platformCustomerId` on a customer create call collides with an existing active customer on the same platform | enum: - TRANSACTION_NOT_PENDING_PLATFORM_APPROVAL @@ -12611,6 +12620,7 @@ components: - EMAIL_OTP_CREDENTIAL_SET_CHANGED - PASSKEY_ALREADY_ENROLLED - SCA_SESSION_REQUIRED + - BENEFICIARY_TRUSTED - CONFLICT message: type: string diff --git a/openapi/components/schemas/errors/Error409.yaml b/openapi/components/schemas/errors/Error409.yaml index f7746d76c..e42e9859f 100644 --- a/openapi/components/schemas/errors/Error409.yaml +++ b/openapi/components/schemas/errors/Error409.yaml @@ -21,6 +21,7 @@ properties: | EMAIL_OTP_CREDENTIAL_SET_CHANGED | Tied EMAIL_OTP credential set changed after the signed-retry challenge was issued | | PASSKEY_ALREADY_ENROLLED | The customer already has an enrolled passkey factor; only one passkey per customer is supported. Delete the existing one before enrolling another | | SCA_SESSION_REQUIRED | The customer's Strong Customer Authentication login session is missing or expired. Re-authenticate the customer, then retry the request. Distinct from a `401`, which means the platform's own API credentials were rejected | + | BENEFICIARY_TRUSTED | The external account is currently a trusted beneficiary, so it cannot be deleted. Untrust it first via `POST /customers/external-accounts/{externalAccountId}/untrust` (and its `/confirm`), then delete | | CONFLICT | Generic resource-state conflict. Returned, for example, when `platformCustomerId` on a customer create call collides with an existing active customer on the same platform | enum: - TRANSACTION_NOT_PENDING_PLATFORM_APPROVAL @@ -30,6 +31,7 @@ properties: - EMAIL_OTP_CREDENTIAL_SET_CHANGED - PASSKEY_ALREADY_ENROLLED - SCA_SESSION_REQUIRED + - BENEFICIARY_TRUSTED - CONFLICT message: type: string diff --git a/openapi/paths/customers/customers_external_accounts_{externalAccountId}.yaml b/openapi/paths/customers/customers_external_accounts_{externalAccountId}.yaml index 338494795..b17db313e 100644 --- a/openapi/paths/customers/customers_external_accounts_{externalAccountId}.yaml +++ b/openapi/paths/customers/customers_external_accounts_{externalAccountId}.yaml @@ -40,7 +40,13 @@ get: $ref: ../../components/schemas/errors/Error500.yaml delete: summary: Delete customer external account by ID - description: Delete a customer external account by its system-generated ID + description: >- + Delete a customer external account by its system-generated ID. + + An account that is currently a trusted beneficiary cannot be deleted — + untrust it first via + `POST /customers/external-accounts/{externalAccountId}/untrust` (and its + `/confirm`), then delete. operationId: deleteCustomerExternalAccountById tags: - External Accounts @@ -61,6 +67,14 @@ delete: application/json: schema: $ref: ../../components/schemas/errors/Error404.yaml + '409': + description: >- + Returned with `BENEFICIARY_TRUSTED` when the external account is + currently a trusted beneficiary. Untrust it first, then delete. + content: + application/json: + schema: + $ref: ../../components/schemas/errors/Error409.yaml '500': description: Internal service error content: From ef4d84951a484c0edad2080344fecb36f964dfee Mon Sep 17 00:00:00 2001 From: Jeremy Klein Date: Wed, 29 Jul 2026 23:48:02 -0700 Subject: [PATCH 2/2] Apply suggestion from @jklein24 --- .../customers_external_accounts_{externalAccountId}.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/openapi/paths/customers/customers_external_accounts_{externalAccountId}.yaml b/openapi/paths/customers/customers_external_accounts_{externalAccountId}.yaml index b17db313e..4792ea0e0 100644 --- a/openapi/paths/customers/customers_external_accounts_{externalAccountId}.yaml +++ b/openapi/paths/customers/customers_external_accounts_{externalAccountId}.yaml @@ -43,7 +43,7 @@ delete: description: >- Delete a customer external account by its system-generated ID. - An account that is currently a trusted beneficiary cannot be deleted — + An account that is currently a trusted beneficiary for SCA cannot be deleted — untrust it first via `POST /customers/external-accounts/{externalAccountId}/untrust` (and its `/confirm`), then delete.