From 165985eb0100e46e12e4fcf9e6289424d290678a Mon Sep 17 00:00:00 2001 From: Jeremy Klein Date: Sat, 23 May 2026 15:37:33 -0700 Subject: [PATCH 1/3] docs(spec): document new error codes from AT-5324 epic MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds the server-side error codes introduced across the AT-5324 error-audit epic so SDK clients can encode against them without triggering each error in production. New codes documented: - 401: WALLET_SIGNATURE_MISSING / MALFORMED / BODY_MISMATCH / INVALID (sparkcore PR #27767, AT-5342) - 404: UMA_NOT_FOUND (PR #27758, AT-5345) - 405: METHOD_NOT_ALLOWED (PR #27747, AT-5325) - 409: CONFLICT, surfaced for duplicate platformCustomerId (PR #27766, AT-5348) - 502: VASP_UNREACHABLE / VASP_INVALID_RESPONSE (PR #27758, AT-5345) Also wires the new 502 response into GET /receiver/uma/{receiverUmaAddress} and 405 into POST /customers, updates the 404 and 409 response descriptions to call out the new codes, and re-bundles openapi.yaml + mintlify/openapi.yaml. No schema redesign — only enum extensions. See error-audit/FRESH_REVIEW.md cross-cutting observation #3 for the underlying gap. --- mintlify/openapi.yaml | 84 ++++++++++++++++++- openapi.yaml | 84 ++++++++++++++++++- .../components/schemas/errors/Error401.yaml | 8 ++ .../components/schemas/errors/Error404.yaml | 2 + .../components/schemas/errors/Error405.yaml | 26 ++++++ .../components/schemas/errors/Error409.yaml | 2 + .../components/schemas/errors/Error502.yaml | 28 +++++++ openapi/paths/customers/customers.yaml | 13 ++- .../receiver_uma_{receiverUmaAddress}.yaml | 16 +++- 9 files changed, 256 insertions(+), 7 deletions(-) create mode 100644 openapi/components/schemas/errors/Error405.yaml create mode 100644 openapi/components/schemas/errors/Error502.yaml diff --git a/mintlify/openapi.yaml b/mintlify/openapi.yaml index 6a2a8401..41308f6d 100644 --- a/mintlify/openapi.yaml +++ b/mintlify/openapi.yaml @@ -424,8 +424,14 @@ paths: application/json: schema: $ref: '#/components/schemas/Error401' + '405': + description: Method not allowed. Returned (as JSON, not HTML) when the request uses an HTTP method that is not supported on this path. + content: + application/json: + schema: + $ref: '#/components/schemas/Error405' '409': - description: Conflict - Customer with the UMA address already exists + description: Conflict. `UMA_ADDRESS_EXISTS` when the requested UMA address is already taken; `CONFLICT` when `platformCustomerId` collides with an existing active customer on the same platform. content: application/json: schema: @@ -2179,7 +2185,7 @@ paths: schema: $ref: '#/components/schemas/Error401' '404': - description: UMA address not found + description: UMA address not found. The address is well-formed but no receiver exists at the counterparty VASP (`UMA_NOT_FOUND`). content: application/json: schema: @@ -2202,6 +2208,12 @@ paths: application/json: schema: $ref: '#/components/schemas/Error500' + '502': + description: Counterparty VASP failure. `VASP_UNREACHABLE` for network, DNS, or TLS errors reaching the counterparty; `VASP_INVALID_RESPONSE` when the counterparty returns a response that can't be parsed or violates the UMA protocol. Both are retryable. + content: + application/json: + schema: + $ref: '#/components/schemas/Error502' /receiver/external-account/{accountId}: get: summary: Look up an external account for payment @@ -8057,9 +8069,17 @@ components: |------------|-------------| | UNAUTHORIZED | Issue with API credentials | | INVALID_SIGNATURE | Signature header is invalid | + | WALLET_SIGNATURE_MISSING | The `Grid-Wallet-Signature` header is required for this Embedded Wallet action but was not supplied | + | WALLET_SIGNATURE_MALFORMED | The `Grid-Wallet-Signature` header could not be parsed (bad encoding, structure, or fields) | + | WALLET_SIGNATURE_BODY_MISMATCH | The `Grid-Wallet-Signature` was computed over a different request body than the one received | + | WALLET_SIGNATURE_INVALID | The `Grid-Wallet-Signature` failed cryptographic verification against the registered credential | enum: - UNAUTHORIZED - INVALID_SIGNATURE + - WALLET_SIGNATURE_MISSING + - WALLET_SIGNATURE_MALFORMED + - WALLET_SIGNATURE_BODY_MISMATCH + - WALLET_SIGNATURE_INVALID message: type: string description: Error message @@ -8964,6 +8984,33 @@ components: mapping: INDIVIDUAL: '#/components/schemas/IndividualCustomerCreateRequest' BUSINESS: '#/components/schemas/BusinessCustomerCreateRequest' + Error405: + type: object + required: + - message + - status + - code + properties: + status: + type: integer + enum: + - 405 + description: HTTP status code + code: + type: string + description: | + | Error Code | Description | + |------------|-------------| + | METHOD_NOT_ALLOWED | The HTTP method is not supported for this endpoint | + enum: + - METHOD_NOT_ALLOWED + message: + type: string + description: Error message + details: + type: object + description: Additional error details + additionalProperties: true Error409: type: object required: @@ -8985,11 +9032,13 @@ components: | UMA_ADDRESS_EXISTS | UMA address already exists | | EMAIL_OTP_EMAIL_ALREADY_EXISTS | Email address is already associated with an EMAIL_OTP credential | | EMAIL_OTP_CREDENTIAL_SET_CHANGED | Tied EMAIL_OTP credential set changed after the signed-retry challenge was issued | + | 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 - UMA_ADDRESS_EXISTS - EMAIL_OTP_EMAIL_ALREADY_EXISTS - EMAIL_OTP_CREDENTIAL_SET_CHANGED + - CONFLICT message: type: string description: Error message @@ -9022,6 +9071,7 @@ components: | TOKEN_NOT_FOUND | Token not found | | BULK_UPLOAD_JOB_NOT_FOUND | Bulk upload job not found | | REFERENCE_NOT_FOUND | Reference not found | + | UMA_NOT_FOUND | The UMA address is well-formed but no receiver exists at the counterparty VASP | enum: - TRANSACTION_NOT_FOUND - INVITATION_NOT_FOUND @@ -9031,6 +9081,7 @@ components: - TOKEN_NOT_FOUND - BULK_UPLOAD_JOB_NOT_FOUND - REFERENCE_NOT_FOUND + - UMA_NOT_FOUND message: type: string description: Error message @@ -16006,6 +16057,35 @@ components: type: object description: Additional error details additionalProperties: true + Error502: + type: object + required: + - message + - status + - code + properties: + status: + type: integer + enum: + - 502 + description: HTTP status code + code: + type: string + description: | + | Error Code | Description | + |------------|-------------| + | VASP_UNREACHABLE | The counterparty VASP could not be reached (DNS, TLS, or network failure). Retryable. | + | VASP_INVALID_RESPONSE | The counterparty VASP returned a response that could not be parsed or violated the UMA protocol | + enum: + - VASP_UNREACHABLE + - VASP_INVALID_RESPONSE + message: + type: string + description: Error message + details: + type: object + description: Additional error details + additionalProperties: true ReceiverExternalAccountLookupResponse: allOf: - $ref: '#/components/schemas/ReceiverLookupResponse' diff --git a/openapi.yaml b/openapi.yaml index 6a2a8401..41308f6d 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -424,8 +424,14 @@ paths: application/json: schema: $ref: '#/components/schemas/Error401' + '405': + description: Method not allowed. Returned (as JSON, not HTML) when the request uses an HTTP method that is not supported on this path. + content: + application/json: + schema: + $ref: '#/components/schemas/Error405' '409': - description: Conflict - Customer with the UMA address already exists + description: Conflict. `UMA_ADDRESS_EXISTS` when the requested UMA address is already taken; `CONFLICT` when `platformCustomerId` collides with an existing active customer on the same platform. content: application/json: schema: @@ -2179,7 +2185,7 @@ paths: schema: $ref: '#/components/schemas/Error401' '404': - description: UMA address not found + description: UMA address not found. The address is well-formed but no receiver exists at the counterparty VASP (`UMA_NOT_FOUND`). content: application/json: schema: @@ -2202,6 +2208,12 @@ paths: application/json: schema: $ref: '#/components/schemas/Error500' + '502': + description: Counterparty VASP failure. `VASP_UNREACHABLE` for network, DNS, or TLS errors reaching the counterparty; `VASP_INVALID_RESPONSE` when the counterparty returns a response that can't be parsed or violates the UMA protocol. Both are retryable. + content: + application/json: + schema: + $ref: '#/components/schemas/Error502' /receiver/external-account/{accountId}: get: summary: Look up an external account for payment @@ -8057,9 +8069,17 @@ components: |------------|-------------| | UNAUTHORIZED | Issue with API credentials | | INVALID_SIGNATURE | Signature header is invalid | + | WALLET_SIGNATURE_MISSING | The `Grid-Wallet-Signature` header is required for this Embedded Wallet action but was not supplied | + | WALLET_SIGNATURE_MALFORMED | The `Grid-Wallet-Signature` header could not be parsed (bad encoding, structure, or fields) | + | WALLET_SIGNATURE_BODY_MISMATCH | The `Grid-Wallet-Signature` was computed over a different request body than the one received | + | WALLET_SIGNATURE_INVALID | The `Grid-Wallet-Signature` failed cryptographic verification against the registered credential | enum: - UNAUTHORIZED - INVALID_SIGNATURE + - WALLET_SIGNATURE_MISSING + - WALLET_SIGNATURE_MALFORMED + - WALLET_SIGNATURE_BODY_MISMATCH + - WALLET_SIGNATURE_INVALID message: type: string description: Error message @@ -8964,6 +8984,33 @@ components: mapping: INDIVIDUAL: '#/components/schemas/IndividualCustomerCreateRequest' BUSINESS: '#/components/schemas/BusinessCustomerCreateRequest' + Error405: + type: object + required: + - message + - status + - code + properties: + status: + type: integer + enum: + - 405 + description: HTTP status code + code: + type: string + description: | + | Error Code | Description | + |------------|-------------| + | METHOD_NOT_ALLOWED | The HTTP method is not supported for this endpoint | + enum: + - METHOD_NOT_ALLOWED + message: + type: string + description: Error message + details: + type: object + description: Additional error details + additionalProperties: true Error409: type: object required: @@ -8985,11 +9032,13 @@ components: | UMA_ADDRESS_EXISTS | UMA address already exists | | EMAIL_OTP_EMAIL_ALREADY_EXISTS | Email address is already associated with an EMAIL_OTP credential | | EMAIL_OTP_CREDENTIAL_SET_CHANGED | Tied EMAIL_OTP credential set changed after the signed-retry challenge was issued | + | 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 - UMA_ADDRESS_EXISTS - EMAIL_OTP_EMAIL_ALREADY_EXISTS - EMAIL_OTP_CREDENTIAL_SET_CHANGED + - CONFLICT message: type: string description: Error message @@ -9022,6 +9071,7 @@ components: | TOKEN_NOT_FOUND | Token not found | | BULK_UPLOAD_JOB_NOT_FOUND | Bulk upload job not found | | REFERENCE_NOT_FOUND | Reference not found | + | UMA_NOT_FOUND | The UMA address is well-formed but no receiver exists at the counterparty VASP | enum: - TRANSACTION_NOT_FOUND - INVITATION_NOT_FOUND @@ -9031,6 +9081,7 @@ components: - TOKEN_NOT_FOUND - BULK_UPLOAD_JOB_NOT_FOUND - REFERENCE_NOT_FOUND + - UMA_NOT_FOUND message: type: string description: Error message @@ -16006,6 +16057,35 @@ components: type: object description: Additional error details additionalProperties: true + Error502: + type: object + required: + - message + - status + - code + properties: + status: + type: integer + enum: + - 502 + description: HTTP status code + code: + type: string + description: | + | Error Code | Description | + |------------|-------------| + | VASP_UNREACHABLE | The counterparty VASP could not be reached (DNS, TLS, or network failure). Retryable. | + | VASP_INVALID_RESPONSE | The counterparty VASP returned a response that could not be parsed or violated the UMA protocol | + enum: + - VASP_UNREACHABLE + - VASP_INVALID_RESPONSE + message: + type: string + description: Error message + details: + type: object + description: Additional error details + additionalProperties: true ReceiverExternalAccountLookupResponse: allOf: - $ref: '#/components/schemas/ReceiverLookupResponse' diff --git a/openapi/components/schemas/errors/Error401.yaml b/openapi/components/schemas/errors/Error401.yaml index d92fb3b7..508f56ba 100644 --- a/openapi/components/schemas/errors/Error401.yaml +++ b/openapi/components/schemas/errors/Error401.yaml @@ -16,9 +16,17 @@ properties: |------------|-------------| | UNAUTHORIZED | Issue with API credentials | | INVALID_SIGNATURE | Signature header is invalid | + | WALLET_SIGNATURE_MISSING | The `Grid-Wallet-Signature` header is required for this Embedded Wallet action but was not supplied | + | WALLET_SIGNATURE_MALFORMED | The `Grid-Wallet-Signature` header could not be parsed (bad encoding, structure, or fields) | + | WALLET_SIGNATURE_BODY_MISMATCH | The `Grid-Wallet-Signature` was computed over a different request body than the one received | + | WALLET_SIGNATURE_INVALID | The `Grid-Wallet-Signature` failed cryptographic verification against the registered credential | enum: - UNAUTHORIZED - INVALID_SIGNATURE + - WALLET_SIGNATURE_MISSING + - WALLET_SIGNATURE_MALFORMED + - WALLET_SIGNATURE_BODY_MISMATCH + - WALLET_SIGNATURE_INVALID message: type: string description: Error message diff --git a/openapi/components/schemas/errors/Error404.yaml b/openapi/components/schemas/errors/Error404.yaml index d53ff414..3f4cab3b 100644 --- a/openapi/components/schemas/errors/Error404.yaml +++ b/openapi/components/schemas/errors/Error404.yaml @@ -22,6 +22,7 @@ properties: | TOKEN_NOT_FOUND | Token not found | | BULK_UPLOAD_JOB_NOT_FOUND | Bulk upload job not found | | REFERENCE_NOT_FOUND | Reference not found | + | UMA_NOT_FOUND | The UMA address is well-formed but no receiver exists at the counterparty VASP | enum: - TRANSACTION_NOT_FOUND - INVITATION_NOT_FOUND @@ -31,6 +32,7 @@ properties: - TOKEN_NOT_FOUND - BULK_UPLOAD_JOB_NOT_FOUND - REFERENCE_NOT_FOUND + - UMA_NOT_FOUND message: type: string description: Error message diff --git a/openapi/components/schemas/errors/Error405.yaml b/openapi/components/schemas/errors/Error405.yaml new file mode 100644 index 00000000..fd25307a --- /dev/null +++ b/openapi/components/schemas/errors/Error405.yaml @@ -0,0 +1,26 @@ +type: object +required: + - message + - status + - code +properties: + status: + type: integer + enum: + - 405 + description: HTTP status code + code: + type: string + description: | + | Error Code | Description | + |------------|-------------| + | METHOD_NOT_ALLOWED | The HTTP method is not supported for this endpoint | + enum: + - METHOD_NOT_ALLOWED + message: + type: string + description: Error message + details: + type: object + description: Additional error details + additionalProperties: true diff --git a/openapi/components/schemas/errors/Error409.yaml b/openapi/components/schemas/errors/Error409.yaml index 160abb37..09db54cb 100644 --- a/openapi/components/schemas/errors/Error409.yaml +++ b/openapi/components/schemas/errors/Error409.yaml @@ -18,11 +18,13 @@ properties: | UMA_ADDRESS_EXISTS | UMA address already exists | | EMAIL_OTP_EMAIL_ALREADY_EXISTS | Email address is already associated with an EMAIL_OTP credential | | EMAIL_OTP_CREDENTIAL_SET_CHANGED | Tied EMAIL_OTP credential set changed after the signed-retry challenge was issued | + | 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 - UMA_ADDRESS_EXISTS - EMAIL_OTP_EMAIL_ALREADY_EXISTS - EMAIL_OTP_CREDENTIAL_SET_CHANGED + - CONFLICT message: type: string description: Error message diff --git a/openapi/components/schemas/errors/Error502.yaml b/openapi/components/schemas/errors/Error502.yaml new file mode 100644 index 00000000..c1057095 --- /dev/null +++ b/openapi/components/schemas/errors/Error502.yaml @@ -0,0 +1,28 @@ +type: object +required: + - message + - status + - code +properties: + status: + type: integer + enum: + - 502 + description: HTTP status code + code: + type: string + description: | + | Error Code | Description | + |------------|-------------| + | VASP_UNREACHABLE | The counterparty VASP could not be reached (DNS, TLS, or network failure). Retryable. | + | VASP_INVALID_RESPONSE | The counterparty VASP returned a response that could not be parsed or violated the UMA protocol | + enum: + - VASP_UNREACHABLE + - VASP_INVALID_RESPONSE + message: + type: string + description: Error message + details: + type: object + description: Additional error details + additionalProperties: true diff --git a/openapi/paths/customers/customers.yaml b/openapi/paths/customers/customers.yaml index e8a9923b..76a7aa42 100644 --- a/openapi/paths/customers/customers.yaml +++ b/openapi/paths/customers/customers.yaml @@ -90,11 +90,22 @@ post: schema: $ref: ../../components/schemas/errors/Error401.yaml '409': - description: Conflict - Customer with the UMA address already exists + description: >- + Conflict. `UMA_ADDRESS_EXISTS` when the requested UMA address is + already taken; `CONFLICT` when `platformCustomerId` collides with + an existing active customer on the same platform. content: application/json: schema: $ref: ../../components/schemas/errors/Error409.yaml + '405': + description: >- + Method not allowed. Returned (as JSON, not HTML) when the request + uses an HTTP method that is not supported on this path. + content: + application/json: + schema: + $ref: ../../components/schemas/errors/Error405.yaml '500': description: Internal service error content: diff --git a/openapi/paths/receiver/uma/receiver_uma_{receiverUmaAddress}.yaml b/openapi/paths/receiver/uma/receiver_uma_{receiverUmaAddress}.yaml index 15e211a4..fcbb08f1 100644 --- a/openapi/paths/receiver/uma/receiver_uma_{receiverUmaAddress}.yaml +++ b/openapi/paths/receiver/uma/receiver_uma_{receiverUmaAddress}.yaml @@ -50,7 +50,9 @@ get: schema: $ref: ../../../components/schemas/errors/Error401.yaml '404': - description: UMA address not found + description: >- + UMA address not found. The address is well-formed but no receiver + exists at the counterparty VASP (`UMA_NOT_FOUND`). content: application/json: schema: @@ -72,4 +74,14 @@ get: content: application/json: schema: - $ref: ../../../components/schemas/errors/Error500.yaml \ No newline at end of file + $ref: ../../../components/schemas/errors/Error500.yaml + '502': + description: >- + Counterparty VASP failure. `VASP_UNREACHABLE` for network, DNS, or + TLS errors reaching the counterparty; `VASP_INVALID_RESPONSE` when + the counterparty returns a response that can't be parsed or violates + the UMA protocol. Both are retryable. + content: + application/json: + schema: + $ref: ../../../components/schemas/errors/Error502.yaml \ No newline at end of file From c40504ecd2d574f4c816073a93a86148f32cb2e1 Mon Sep 17 00:00:00 2001 From: Jeremy Klein Date: Sat, 23 May 2026 16:17:14 -0700 Subject: [PATCH 2/3] address greptile review feedback (greploop iteration 1) - Mark VASP_INVALID_RESPONSE as Retryable in Error502 schema to match path-level description - Reorder 405 before 409 in POST /customers responses for numeric ordering - Document 405 METHOD_NOT_ALLOWED on GET /customers as well - Add trailing newline to receiver_uma_{receiverUmaAddress}.yaml --- mintlify/openapi.yaml | 62 ++++++++++--------- openapi.yaml | 62 ++++++++++--------- .../components/schemas/errors/Error502.yaml | 2 +- openapi/paths/customers/customers.yaml | 24 ++++--- .../receiver_uma_{receiverUmaAddress}.yaml | 2 +- 5 files changed, 86 insertions(+), 66 deletions(-) diff --git a/mintlify/openapi.yaml b/mintlify/openapi.yaml index 41308f6d..4fb59bd9 100644 --- a/mintlify/openapi.yaml +++ b/mintlify/openapi.yaml @@ -557,6 +557,12 @@ paths: application/json: schema: $ref: '#/components/schemas/Error401' + '405': + description: Method not allowed. Returned (as JSON, not HTML) when the request uses an HTTP method that is not supported on this path. + content: + application/json: + schema: + $ref: '#/components/schemas/Error405' '500': description: Internal service error content: @@ -8929,6 +8935,33 @@ components: totalCount: type: integer description: Total number of customers matching the criteria (excluding pagination) + Error405: + type: object + required: + - message + - status + - code + properties: + status: + type: integer + enum: + - 405 + description: HTTP status code + code: + type: string + description: | + | Error Code | Description | + |------------|-------------| + | METHOD_NOT_ALLOWED | The HTTP method is not supported for this endpoint | + enum: + - METHOD_NOT_ALLOWED + message: + type: string + description: Error message + details: + type: object + description: Additional error details + additionalProperties: true CustomerCreateRequest: type: object required: @@ -8984,33 +9017,6 @@ components: mapping: INDIVIDUAL: '#/components/schemas/IndividualCustomerCreateRequest' BUSINESS: '#/components/schemas/BusinessCustomerCreateRequest' - Error405: - type: object - required: - - message - - status - - code - properties: - status: - type: integer - enum: - - 405 - description: HTTP status code - code: - type: string - description: | - | Error Code | Description | - |------------|-------------| - | METHOD_NOT_ALLOWED | The HTTP method is not supported for this endpoint | - enum: - - METHOD_NOT_ALLOWED - message: - type: string - description: Error message - details: - type: object - description: Additional error details - additionalProperties: true Error409: type: object required: @@ -16075,7 +16081,7 @@ components: | Error Code | Description | |------------|-------------| | VASP_UNREACHABLE | The counterparty VASP could not be reached (DNS, TLS, or network failure). Retryable. | - | VASP_INVALID_RESPONSE | The counterparty VASP returned a response that could not be parsed or violated the UMA protocol | + | VASP_INVALID_RESPONSE | The counterparty VASP returned a response that could not be parsed or violated the UMA protocol. Retryable. | enum: - VASP_UNREACHABLE - VASP_INVALID_RESPONSE diff --git a/openapi.yaml b/openapi.yaml index 41308f6d..4fb59bd9 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -557,6 +557,12 @@ paths: application/json: schema: $ref: '#/components/schemas/Error401' + '405': + description: Method not allowed. Returned (as JSON, not HTML) when the request uses an HTTP method that is not supported on this path. + content: + application/json: + schema: + $ref: '#/components/schemas/Error405' '500': description: Internal service error content: @@ -8929,6 +8935,33 @@ components: totalCount: type: integer description: Total number of customers matching the criteria (excluding pagination) + Error405: + type: object + required: + - message + - status + - code + properties: + status: + type: integer + enum: + - 405 + description: HTTP status code + code: + type: string + description: | + | Error Code | Description | + |------------|-------------| + | METHOD_NOT_ALLOWED | The HTTP method is not supported for this endpoint | + enum: + - METHOD_NOT_ALLOWED + message: + type: string + description: Error message + details: + type: object + description: Additional error details + additionalProperties: true CustomerCreateRequest: type: object required: @@ -8984,33 +9017,6 @@ components: mapping: INDIVIDUAL: '#/components/schemas/IndividualCustomerCreateRequest' BUSINESS: '#/components/schemas/BusinessCustomerCreateRequest' - Error405: - type: object - required: - - message - - status - - code - properties: - status: - type: integer - enum: - - 405 - description: HTTP status code - code: - type: string - description: | - | Error Code | Description | - |------------|-------------| - | METHOD_NOT_ALLOWED | The HTTP method is not supported for this endpoint | - enum: - - METHOD_NOT_ALLOWED - message: - type: string - description: Error message - details: - type: object - description: Additional error details - additionalProperties: true Error409: type: object required: @@ -16075,7 +16081,7 @@ components: | Error Code | Description | |------------|-------------| | VASP_UNREACHABLE | The counterparty VASP could not be reached (DNS, TLS, or network failure). Retryable. | - | VASP_INVALID_RESPONSE | The counterparty VASP returned a response that could not be parsed or violated the UMA protocol | + | VASP_INVALID_RESPONSE | The counterparty VASP returned a response that could not be parsed or violated the UMA protocol. Retryable. | enum: - VASP_UNREACHABLE - VASP_INVALID_RESPONSE diff --git a/openapi/components/schemas/errors/Error502.yaml b/openapi/components/schemas/errors/Error502.yaml index c1057095..902b7efc 100644 --- a/openapi/components/schemas/errors/Error502.yaml +++ b/openapi/components/schemas/errors/Error502.yaml @@ -15,7 +15,7 @@ properties: | Error Code | Description | |------------|-------------| | VASP_UNREACHABLE | The counterparty VASP could not be reached (DNS, TLS, or network failure). Retryable. | - | VASP_INVALID_RESPONSE | The counterparty VASP returned a response that could not be parsed or violated the UMA protocol | + | VASP_INVALID_RESPONSE | The counterparty VASP returned a response that could not be parsed or violated the UMA protocol. Retryable. | enum: - VASP_UNREACHABLE - VASP_INVALID_RESPONSE diff --git a/openapi/paths/customers/customers.yaml b/openapi/paths/customers/customers.yaml index 76a7aa42..c0eddd2c 100644 --- a/openapi/paths/customers/customers.yaml +++ b/openapi/paths/customers/customers.yaml @@ -89,6 +89,14 @@ post: application/json: schema: $ref: ../../components/schemas/errors/Error401.yaml + '405': + description: >- + Method not allowed. Returned (as JSON, not HTML) when the request + uses an HTTP method that is not supported on this path. + content: + application/json: + schema: + $ref: ../../components/schemas/errors/Error405.yaml '409': description: >- Conflict. `UMA_ADDRESS_EXISTS` when the requested UMA address is @@ -98,14 +106,6 @@ post: application/json: schema: $ref: ../../components/schemas/errors/Error409.yaml - '405': - description: >- - Method not allowed. Returned (as JSON, not HTML) when the request - uses an HTTP method that is not supported on this path. - content: - application/json: - schema: - $ref: ../../components/schemas/errors/Error405.yaml '500': description: Internal service error content: @@ -230,6 +230,14 @@ get: application/json: schema: $ref: ../../components/schemas/errors/Error401.yaml + '405': + description: >- + Method not allowed. Returned (as JSON, not HTML) when the request + uses an HTTP method that is not supported on this path. + content: + application/json: + schema: + $ref: ../../components/schemas/errors/Error405.yaml '500': description: Internal service error content: diff --git a/openapi/paths/receiver/uma/receiver_uma_{receiverUmaAddress}.yaml b/openapi/paths/receiver/uma/receiver_uma_{receiverUmaAddress}.yaml index fcbb08f1..57914e78 100644 --- a/openapi/paths/receiver/uma/receiver_uma_{receiverUmaAddress}.yaml +++ b/openapi/paths/receiver/uma/receiver_uma_{receiverUmaAddress}.yaml @@ -84,4 +84,4 @@ get: content: application/json: schema: - $ref: ../../../components/schemas/errors/Error502.yaml \ No newline at end of file + $ref: ../../../components/schemas/errors/Error502.yaml From 3a8083a10d3c20e270876d9fd5f8612cdb23ab68 Mon Sep 17 00:00:00 2001 From: Jeremy Klein Date: Sun, 24 May 2026 23:36:26 -0700 Subject: [PATCH 3/3] Remove 502 / VASP_UNREACHABLE / VASP_INVALID_RESPONSE from spec Dropping the 502 documentation since AT-5345 (the server-side change that would have introduced these codes) was closed without merging. The spec shouldn't document codes the server doesn't emit. - Delete openapi/components/schemas/errors/Error502.yaml - Drop the '502' response from POST /receiver/uma/{receiverUmaAddress} - Re-bundle openapi.yaml + mintlify/openapi.yaml --- mintlify/openapi.yaml | 35 ------------------- openapi.yaml | 35 ------------------- .../components/schemas/errors/Error502.yaml | 28 --------------- .../receiver_uma_{receiverUmaAddress}.yaml | 10 ------ 4 files changed, 108 deletions(-) delete mode 100644 openapi/components/schemas/errors/Error502.yaml diff --git a/mintlify/openapi.yaml b/mintlify/openapi.yaml index 4fb59bd9..dd086e0a 100644 --- a/mintlify/openapi.yaml +++ b/mintlify/openapi.yaml @@ -2214,12 +2214,6 @@ paths: application/json: schema: $ref: '#/components/schemas/Error500' - '502': - description: Counterparty VASP failure. `VASP_UNREACHABLE` for network, DNS, or TLS errors reaching the counterparty; `VASP_INVALID_RESPONSE` when the counterparty returns a response that can't be parsed or violates the UMA protocol. Both are retryable. - content: - application/json: - schema: - $ref: '#/components/schemas/Error502' /receiver/external-account/{accountId}: get: summary: Look up an external account for payment @@ -16063,35 +16057,6 @@ components: type: object description: Additional error details additionalProperties: true - Error502: - type: object - required: - - message - - status - - code - properties: - status: - type: integer - enum: - - 502 - description: HTTP status code - code: - type: string - description: | - | Error Code | Description | - |------------|-------------| - | VASP_UNREACHABLE | The counterparty VASP could not be reached (DNS, TLS, or network failure). Retryable. | - | VASP_INVALID_RESPONSE | The counterparty VASP returned a response that could not be parsed or violated the UMA protocol. Retryable. | - enum: - - VASP_UNREACHABLE - - VASP_INVALID_RESPONSE - message: - type: string - description: Error message - details: - type: object - description: Additional error details - additionalProperties: true ReceiverExternalAccountLookupResponse: allOf: - $ref: '#/components/schemas/ReceiverLookupResponse' diff --git a/openapi.yaml b/openapi.yaml index 4fb59bd9..dd086e0a 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -2214,12 +2214,6 @@ paths: application/json: schema: $ref: '#/components/schemas/Error500' - '502': - description: Counterparty VASP failure. `VASP_UNREACHABLE` for network, DNS, or TLS errors reaching the counterparty; `VASP_INVALID_RESPONSE` when the counterparty returns a response that can't be parsed or violates the UMA protocol. Both are retryable. - content: - application/json: - schema: - $ref: '#/components/schemas/Error502' /receiver/external-account/{accountId}: get: summary: Look up an external account for payment @@ -16063,35 +16057,6 @@ components: type: object description: Additional error details additionalProperties: true - Error502: - type: object - required: - - message - - status - - code - properties: - status: - type: integer - enum: - - 502 - description: HTTP status code - code: - type: string - description: | - | Error Code | Description | - |------------|-------------| - | VASP_UNREACHABLE | The counterparty VASP could not be reached (DNS, TLS, or network failure). Retryable. | - | VASP_INVALID_RESPONSE | The counterparty VASP returned a response that could not be parsed or violated the UMA protocol. Retryable. | - enum: - - VASP_UNREACHABLE - - VASP_INVALID_RESPONSE - message: - type: string - description: Error message - details: - type: object - description: Additional error details - additionalProperties: true ReceiverExternalAccountLookupResponse: allOf: - $ref: '#/components/schemas/ReceiverLookupResponse' diff --git a/openapi/components/schemas/errors/Error502.yaml b/openapi/components/schemas/errors/Error502.yaml deleted file mode 100644 index 902b7efc..00000000 --- a/openapi/components/schemas/errors/Error502.yaml +++ /dev/null @@ -1,28 +0,0 @@ -type: object -required: - - message - - status - - code -properties: - status: - type: integer - enum: - - 502 - description: HTTP status code - code: - type: string - description: | - | Error Code | Description | - |------------|-------------| - | VASP_UNREACHABLE | The counterparty VASP could not be reached (DNS, TLS, or network failure). Retryable. | - | VASP_INVALID_RESPONSE | The counterparty VASP returned a response that could not be parsed or violated the UMA protocol. Retryable. | - enum: - - VASP_UNREACHABLE - - VASP_INVALID_RESPONSE - message: - type: string - description: Error message - details: - type: object - description: Additional error details - additionalProperties: true diff --git a/openapi/paths/receiver/uma/receiver_uma_{receiverUmaAddress}.yaml b/openapi/paths/receiver/uma/receiver_uma_{receiverUmaAddress}.yaml index 57914e78..05ca56b8 100644 --- a/openapi/paths/receiver/uma/receiver_uma_{receiverUmaAddress}.yaml +++ b/openapi/paths/receiver/uma/receiver_uma_{receiverUmaAddress}.yaml @@ -75,13 +75,3 @@ get: application/json: schema: $ref: ../../../components/schemas/errors/Error500.yaml - '502': - description: >- - Counterparty VASP failure. `VASP_UNREACHABLE` for network, DNS, or - TLS errors reaching the counterparty; `VASP_INVALID_RESPONSE` when - the counterparty returns a response that can't be parsed or violates - the UMA protocol. Both are retryable. - content: - application/json: - schema: - $ref: ../../../components/schemas/errors/Error502.yaml