openapi: 3.1.0
info:
  title: Outbound Eligibility API
  version: v1.0.0-draft
  description: |
    The Outbound Eligibility API (OEA) is an interface definition for a
    service that partner implements on their own servers. It defines how the
    Bango Platform sends all types of consumer eligibility requests to partners.
    
    # Change log
    **2025-04-21** | v.0.0.3
     - Formatting fixes

    **2025-02-06** | v.0.0.2
     - Add user-terminated code for ELIGIBILITY_DENIED
     - Support optional billingIdentifier field in request
     - Additional fields

    **2024-11-15** | v.0.0.1
    - Updated Outbound-Eligibility-API request/response models
security:
  - basic: []
paths:
  "/{partnerUrlForEligibilityCheck}":
    post:
      operationId: send-request-outbound
      summary: Send an eligibility request to a partner
      description: >
        The Bango Platform uses this endpoint to send an eligibility
        request to a partner.


        Every request sent may result in a range of possible responses from the partner.


        Every request will include a unique `requestId` property (UUID v4). This identifies the request and is not used for any other purpose. The corresponding response to the request must include the `requestId`.


        ### HTTP responses


        The Bango Platform always sends a request to the partner over HTTP, and the partner must return an HTTP response. HTTP requests contain request types as defined in this specification.


        The HTTP response MUST be one of the following:

        - HTTP 200 OK - containing a response payload in the response body. Each request defines the expected responses

        - HTTP 4xx - indicating a problem with the request

        - HTTP 5xx - indicating a problem with the partner system


        This specification defines the shape of HTTP 4xx and 5xx responses. These all have a response body containing an `errors` array, each member of which is an object containing an error `code` and other data.


        If a request to a partner times out, this is treated the same as an HTTP 503 error from the partner with `canRetry: true`.


        #### HTTP 400 BAD REQUEST responses


        For HTTP 400 BAD REQUEST responses specifically, the partner MUST use these values for `code` for the error conditions listed:


        - `invalid-json`
          - If the request body isn't valid JSON format
        - `missing-parameter`
          - If any required parameter is not present in the request body. For example, `id`, `type`, `payload`, or any required value inside `payload`.
        - `invalid-parameter`
          - If any parameter in the request is syntactically invalid. For example, if `type` is an integer, or if `id` is not a UUID v4.
          - If any parameter in the request is semantically invalid. For example, if a `payload` field specifies a user identifier and that user isn't recognized by the partner.

        #### HTTP 5xx responses


        HTTP 5xx responses may indicate a problem on the partner's side. This might be a temporary problem caused by a network issue between the Bango Platform and the partner, or it may indicate a more serious, persistent issue.


        Any 5xx response from the partner propagates through the platform as a service error with code `partner-failure`. The 5xx response from the partner may specify that the request can be retried, using the `metadata.canRetry` boolean in the 5xx response.


        A timeout in the connection from the Bango Platform to the partner is always reported as a `partner-failure` that may be retried.
      parameters:
        - in: path
          name: partnerUrlForEligibilityCheck
          required: true
          description: |
            URL used to perform the eligibility check.
          schema:
            type: string
      requestBody:
        description: >
          A request initiated by the Bango Platform, to be processed by the
          partner.


          The following request types are available. See each request type schema for detailed information on purpose and response payload types.


          - `OFFERS_ELIGIBILITY_CHECK`: Ask the partner up-to-date eligibility data across for a specific offer or for all available offers for a consumer.
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - $ref: "#/components/schemas/OFFERS_ELIGIBILITY_CHECK"
      responses:
        "200":
          description: |
            The response payload, which depends on the request type.

              Supported HTTP responses
            - HTTP 200 OK:
              - `ELIGIBILITY_RETRIEVED`
              - `ELIGIBILITY_DENIED`
          content:
            application/vnd.bango.partner-response.v1+json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/ELIGIBILITY_RETRIEVED"
                  - $ref: "#/components/schemas/ELIGIBILITY_DENIED"
        "400":
          description: >
            The response payload, which depends on the request type.

              Supported HTTP responses
            - HTTP 400 BAD REQUEST with one or more errors:
              - `code` == `invalid-json`:
                - the request body is not valid JSON
              - `code` == `missing-parameter`:
                - a required parameter is omitted from the request payload
              - `code` == `invalid-parameter`:
                - a parameter is not of the expected type, or
                - a parameter violates the documented constraints
                - `consumer.consumerId` does not identify a consumer known to the partner
          $ref: "#/components/responses/BadRequestErrorResponse"
        "401":
          $ref: "#/components/responses/InvalidCredentialsErrorResponse"
        "403":
          $ref: "#/components/responses/PermissionDeniedErrorResponse"
        "429":
          $ref: "#/components/responses/TooManyRequestsErrorResponse"
        "500":
          description: |
            An internal server error occurred
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      oneOf:
                        - $ref: "#/components/schemas/partner-internal-server-error"
                        - $ref: "#/components/schemas/partner-failure"
                required:
                  - errors
        "503":
          $ref: "#/components/responses/PartnerServiceUnavailableErrorResponse"
servers:
  - description: Testing environment
    url: https://api.sandbox.bango.com
components:
  securitySchemes:
    basic:
      type: http
      description: Basic authentication
      scheme: basic
  schemas:
    request-id:
      title: Request ID
      description: |
        Unique ID associated with request/response to an API.
      type: string
      format: uuid
      example: 85d814e6-7ca7-4753-8477-5363b67a6091
    consumer-identifier:
      title: Consumer Identifier
      description: >
        A consumer identifier is a unique id that identifies the consumer.
        It should be a unique value that is not reused between individuals, e.g.
        an account number, a user ID, a UUID, an ACR (Account Reference Code) or
        something similar.
      type: string
      minLength: 1
      maxLength: 400
      example: '1007189i2391836'
    billing-identifier:
      title: Billing Identifier
      description: >
        A consumer's billing identifier is a string that identifies a
        consumer's billing account. It could be a subscriber/account number.
      type: string
      minLength: 1
      maxLength: 400
      example: 8899334455
    consumer-properties:
      title: consumer
      description: |
        Consumer identification data to identify the customer.
      type: object
      minProperties: 0
      maxProperties: 50
      unevaluatedProperties:
        type: string
        minLength: 1
        maxLength: 512
      properties:
        consumerIdentifier:
          $ref: "#/components/schemas/consumer-identifier"
        billingIdentifier:
          $ref: "#/components/schemas/billing-identifier"
      required:
        - consumerIdentifier
      example:
        consumerIdentifier: "123456789778"
        billingIdentifier: "08217467445"
    offer-id:
      title: Unique offer identifier
      description: |
        The unique identifier for the offer.
      type: string
      format: uuid
      example: 2adf1639-bb50-4df7-b8a0-79a0cd4f2277
    offers-ids-properties:
      title: list of offers ids
      description: >
        List of offers for which eligibility is checked. MUST contain at
        least one property. All property values MUST be strings.
      type: object
      minProperties: 1
      maxProperties: 50
      unevaluatedProperties:
        type: string
        minLength: 1
        maxLength: 512
      properties:
        offerId:
          $ref: "#/components/schemas/offer-id"
      required:
        - offerId
      example:
        - offerId: a49f0143-7d98-48c1-9f5a-5431294a823c
        - offerId: 8aa12c97-2027-47db-9df8-d62b5205e9fb
    partner-id:
      title: Unique Partner identifier
      description: |
        The unique identifier for the Partner
      type: string
      format: uuid
      example: 2adf1639-bb50-4df7-b8a0-79a0cd4f2277
    OFFERS_ELIGIBILITY_CHECK:
      title: OFFERS_ELIGIBILITY_CHECK request payload (outbound)
      description: >
        Ask the partner for all available offers eligibility up-to-date for
        a consumer.


        The consumer is identified using consumer properties that contains the identification of the consumer, frequently the consumerId.
      type: object
      properties:
        requestId:
          $ref: "#/components/schemas/request-id"
        type:
          description: |
            Indicates the type of the eligibility check being requested.
          type: string
          enum:
            - OFFERS_ELIGIBILITY_CHECK
          example: OFFERS_ELIGIBILITY_CHECK
        payload:
          type: object
          properties:
            consumer:
              $ref: "#/components/schemas/consumer-properties"
              description: |
                Identification data to identify the consumer.
              type: object
            offers:
              description: |
                List of offers for which eligibility is checked.
              $ref: "#/components/schemas/offers-ids-properties"
          additionalProperties: false
          required:
            - consumer
      required:
        - requestId
        - type
        - payload
    offers-properties:
      title: list of offers eligibility properties
      description: >
        MUST contain at least two properties. MAY contain more than two
        properties. All property values MUST be strings.
      type: object
      minProperties: 1
      maxProperties: 50
      unevaluatedProperties:
        type: string
        minLength: 1
        maxLength: 512
      properties:
        offerId:
          $ref: "#/components/schemas/offer-id"
        eligibilityStatus:
          description: |
            Indicates the eligibility status of the offer.
          type: string
          enum:
            - CONSUMER_ELIGIBLE
            - CONSUMER_NOT_ELIGIBLE
            - CONSUMER_ELIGIBILITY_UNKNOWN
            - CONSUMER_ELIGIBILITY_UNSUPPORTED
          example: CONSUMER_ELIGIBLE
        message:
          description: >
            Optional message to indicate why the consumer is not eligible for
            the offer.
          type: string
          minLength: 1
          maxLength: 256
          example:
            Unfortunately you are not eligible to redeem this offer as you are not
            a Super Mega Plus customer
      required:
        - offerId
        - eligibilityStatus
      example:
        offerId: a49f0143-7d98-48c1-9f5a-5431294a823c
        eligibilityStatus: CONSUMER_ELIGIBLE
    eligibility-status:
      title: Payment Eligibility Status
      description: >
        Status of the consumer's billing identifier for payments
        processing.

        - `enabled`: Authorized partners can use the billing identifier to process payments

        - `not-enabled`: Authorized partners cannot use the billing identifier to process payments

        - `closed`: The billing identifier can no longer process payments

        - `barred`: The partner has suspended or barred the billing identifier (this may be temporary)

        - `unknown`: The partner has not provided information about eligibility status

        - `unsupported`: The partner does not support requests about payments eligibility
      type: string
      enum:
        - enabled
        - not-enabled
        - closed
        - barred
        - unknown
        - unsupported
      example: enabled
    account-type:
      title: Partner Account Type
      description: >
        The account type allocated by the partner provider for a consumer's
        account.
      type: string
      enum:
        - prepaid
        - postpaid
        - unknown
    country-code-iso-3166:
      title: ISO 3166-1 alpha-2 country code
      description: >
        A two-character [ISO 3166-1
        alpha-2](https://www.iso.org/iso-3166-country-codes.html) country code.
      type: string
      enum:
        - AF
        - AX
        - AL
        - DZ
        - AS
        - AD
        - AO
        - AI
        - AQ
        - AG
        - AR
        - AM
        - AW
        - AU
        - AT
        - AZ
        - BS
        - BH
        - BD
        - BB
        - BY
        - BE
        - BZ
        - BJ
        - BM
        - BT
        - BO
        - BQ
        - BA
        - BW
        - BV
        - BR
        - IO
        - BN
        - BG
        - BF
        - BI
        - KH
        - CM
        - CA
        - CV
        - KY
        - CF
        - TD
        - CL
        - CN
        - CX
        - CC
        - CO
        - KM
        - CG
        - CD
        - CK
        - CR
        - CI
        - HR
        - CU
        - CW
        - CY
        - CZ
        - DK
        - DJ
        - DM
        - DO
        - EC
        - EG
        - SV
        - GQ
        - ER
        - EE
        - ET
        - FK
        - FO
        - FJ
        - FI
        - FR
        - GF
        - PF
        - TF
        - GA
        - GM
        - GE
        - DE
        - GH
        - GI
        - GR
        - GL
        - GD
        - GP
        - GU
        - GT
        - GG
        - GN
        - GW
        - GY
        - HT
        - HM
        - VA
        - HN
        - HK
        - HU
        - IS
        - IN
        - ID
        - IR
        - IQ
        - IE
        - IM
        - IL
        - IT
        - JM
        - JP
        - JE
        - JO
        - KZ
        - KE
        - KI
        - KP
        - KR
        - KW
        - KG
        - LA
        - LV
        - LB
        - LS
        - LR
        - LY
        - LI
        - LT
        - LU
        - MO
        - MK
        - MG
        - MW
        - MY
        - MV
        - ML
        - MT
        - MH
        - MQ
        - MR
        - MU
        - YT
        - MX
        - FM
        - MD
        - MC
        - MN
        - ME
        - MS
        - MA
        - MZ
        - MM
        - NA
        - NR
        - NP
        - NL
        - NC
        - NZ
        - NI
        - NE
        - NG
        - NU
        - NF
        - MP
        - NO
        - OM
        - PK
        - PW
        - PS
        - PA
        - PG
        - PY
        - PE
        - PH
        - PN
        - PL
        - PT
        - PR
        - QA
        - RE
        - RO
        - RU
        - RW
        - BL
        - SH
        - KN
        - LC
        - MF
        - PM
        - VC
        - WS
        - SM
        - ST
        - SA
        - SN
        - RS
        - SC
        - SL
        - SG
        - SX
        - SK
        - SI
        - SB
        - SO
        - ZA
        - GS
        - SS
        - ES
        - LK
        - SD
        - SR
        - SJ
        - SZ
        - SE
        - CH
        - SY
        - TW
        - TJ
        - TZ
        - TH
        - TL
        - TG
        - TK
        - TO
        - TT
        - TN
        - TR
        - TM
        - TC
        - TV
        - UG
        - UA
        - AE
        - GB
        - US
        - UM
        - UY
        - UZ
        - VU
        - VE
        - VN
        - VG
        - VI
        - WF
        - EH
        - YE
        - ZM
        - ZW
    locale-bcp-47:
      title: BCP 47 language tag
      description: >
        A [BCP 47](https://en.wikipedia.org/wiki/IETF_language_tag) language tag.
      type: string
      minLength: 1
      maxLength: 50
      example:
        - en-US
        - ar-SA
    currency-code-iso-4217:
      title: ISO 4217 3-char currency code
      description: >
        A three-character [ISO
        4217](https://www.iso.org/iso-4217-currency-codes.html) currency code.


        The allowed values are:

        - All current ISO 4217 codes except those for precious metals and bonds

        - ISO 4217 historical codes withdrawn since 2010


        ISO 4217 publication: January 1, 2023
      type: string
      enum:
        - AED
        - AFN
        - ALL
        - AMD
        - ANG
        - AOA
        - ARS
        - AUD
        - AWG
        - AZN
        - BAM
        - BBD
        - BDT
        - BGN
        - BHD
        - BIF
        - BMD
        - BND
        - BOB
        - BOV
        - BRL
        - BSD
        - BTN
        - BWP
        - BYN
        - BYR
        - BZD
        - CAD
        - CDF
        - CHE
        - CHF
        - CHW
        - CLF
        - CLP
        - CNY
        - COP
        - COU
        - CRC
        - CUC
        - CUP
        - CVE
        - CZK
        - DJF
        - DKK
        - DOP
        - DZD
        - EEK
        - EGP
        - ERN
        - ETB
        - EUR
        - FJD
        - FKP
        - GBP
        - GEL
        - GHS
        - GIP
        - GMD
        - GNF
        - GTQ
        - GYD
        - HKD
        - HNL
        - HRK
        - HTG
        - HUF
        - IDR
        - ILS
        - INR
        - IQD
        - IRR
        - ISK
        - JMD
        - JOD
        - JPY
        - KES
        - KGS
        - KHR
        - KMF
        - KPW
        - KRW
        - KWD
        - KYD
        - KZT
        - LAK
        - LBP
        - LKR
        - LRD
        - LSL
        - LTL
        - LVL
        - LYD
        - MAD
        - MDL
        - MGA
        - MKD
        - MMK
        - MNT
        - MOP
        - MRO
        - MRU
        - MUR
        - MVR
        - MWK
        - MXN
        - MXV
        - MYR
        - MZN
        - NAD
        - NGN
        - NIO
        - NOK
        - NPR
        - NZD
        - OMR
        - PAB
        - PEN
        - PGK
        - PHP
        - PKR
        - PLN
        - PYG
        - QAR
        - RON
        - RSD
        - RUB
        - RWF
        - SAR
        - SBD
        - SCR
        - SDG
        - SEK
        - SGD
        - SHP
        - SLE
        - SLL
        - SOS
        - SRD
        - SSP
        - STD
        - STN
        - SVC
        - SYP
        - SZL
        - THB
        - TJS
        - TMT
        - TND
        - TOP
        - TRY
        - TTD
        - TWD
        - TZS
        - UAH
        - UGX
        - USD
        - USN
        - USS
        - UYI
        - UYU
        - UYW
        - UZS
        - VED
        - VEF
        - VES
        - VND
        - VUV
        - WST
        - XAF
        - XCD
        - XDR
        - XFU
        - XOF
        - XPF
        - XSU
        - YER
        - ZAR
        - ZMK
        - ZMW
        - ZWL
      example: USD
    customer-profile:
      title: spending limit profile
      description: |
        Customer’s latest spending limit profile
      type: string
      maxLength: 50
      example: saver
    user-properties:
      title: User Properties
      description: |
        Describes the User Properties data.
      type: object
      properties:
        accountType:
          $ref: "#/components/schemas/account-type"
        countryCode:
          $ref: "#/components/schemas/country-code-iso-3166"
        locale:
          $ref: "#/components/schemas/locale-bcp-47"
        currency:
          $ref: "#/components/schemas/currency-code-iso-4217"
        customerProfile:
          $ref: "#/components/schemas/customer-profile"
    eligibility-data:
      title: Eligibility Data
      description: |
        Describes the eligibility check data.
      type: object
      properties:
        offerEligibility:
          type: object
          description: Offer(s) eligibility information for the consumer.
          properties:
            expiryPeriod:
              type: string
              description: Period for which the offer(s) eligibility is valid for
              example: 20D
            offers:
              type: array
              description: >
                list of all available offers returned by the partner after an
                eligibility check.
              items:
                allOf:
                  - $ref: "#/components/schemas/offers-properties"
              example:
                - offerId: a49f0143-7d98-48c1-9f5a-5431294a823c
                  eligibilityStatus: CONSUMER_ELIGIBLE
                - offerId: 8aa12c97-2027-47db-9df8-d62b5205e9fb
                  eligibilityStatus: CONSUMER_ELIGIBLE
        paymentEligibility:
          type: object
          description:
            Payment eligibility relevant to the billing identifier (if provided
            in the request).
          properties:
            status:
              $ref: "#/components/schemas/eligibility-status"
            expiryPeriod:
              type: string
              description: Period for which the payment(s) eligibility is valid for.
              example: 30D
            userProperties:
              $ref: "#/components/schemas/user-properties"
    ELIGIBILITY_RETRIEVED:
      title: ELIGIBILITY_RETRIEVED response payload
      description: >
        This is one of the two responses to an `OFFERS_ELIGIBILITY_CHECK`
        request. It Contains information about the consumer's eligibility for
        offers. This response is used when any eligibility information was
        provided by the partner.
      type: object
      properties:
        requestId:
          $ref: "#/components/schemas/request-id"
        type:
          const: ELIGIBILITY_RETRIEVED
          description: Indicates the type of eligibility response.
        payload:
          type: object
          properties:
            eligibilityData:
              $ref: "#/components/schemas/eligibility-data"
          additionalProperties: false
      required:
        - requestId
        - type
        - payload
    eligibility-denied-code:
      title: Eligibility denied code
      description: >
        Defines the reason why a partner has denied an eligibility check.

        - `user-suspended`: The user has been suspended

        - `user-terminated`: The user has been terminated        

        - `unsupported`: The partner cannot support eligibility checks

        - `unknown`: The partner has not provided information about eligibility status
      type: string
      minLength: 1
      maxLength: 50
      enum:
        - user-suspended
        - user-terminated
        - unsupported
        - unknown
      example: user-suspended
    ELIGIBILITY_DENIED:
      title: ELIGIBILITY_DENIED response payload
      description: >
        This is the other possible responses to an
        `OFFERS_ELIGIBILITY_CHECK` request. Contains information about the
        consumer's eligibility denial reason. This response is used when partner
        has denied an eligibility check due to some reason.
      type: object
      properties:
        requestId:
          $ref: "#/components/schemas/request-id"
        type:
          const: ELIGIBILITY_DENIED
        payload:
          type: object
          properties:
            code:
              $ref: "#/components/schemas/eligibility-denied-code"
            message:
              description: |
                Message describing reason for denying an eligibility check.
              type: string
              minLength: 1
              maxLength: 256
              example: user has not paid their bill
          additionalProperties: false
          required:
            - code
      required:
        - requestId
        - type
    CommonErrorResponse:
      type: object
      required:
        - errors
    invalid-json:
      title: invalid-json
      description: The request body is not valid JSON
      type: object
      properties:
        code:
          const: invalid-json
        originator:
          description: Additional information to help identify the error origin
          type: string
          example: PARTNER
        metadata:
          description:
            Additional information to help identify the specific error case
            (empty in this case)
          type: object
        message:
          description: Human-readable message describing the error
          type: string
          example: The request body is not valid JSON
      required:
        - code
        - metadata
        - message
    missing-parameter:
      title: missing-parameter
      description: A required parameter is missing from the request
      type: object
      properties:
        code:
          const: missing-parameter
        originator:
          description: Additional information to help identify the error origin
          type: string
          example: PARTNER
        metadata:
          description: Additional information to help identify the specific error case
          type: object
          properties:
            param:
              description: The name of the missing parameter
              type: string
          required:
            - param
        message:
          description: Human-readable message describing the error
          type: string
          example: A required parameter was missing from the request
      required:
        - code
        - meta
        - message
    invalid-parameter:
      title: invalid-parameter
      description: A request parameter is invalid
      type: object
      properties:
        code:
          const: invalid-parameter
        originator:
          description: Additional information to help identify the error origin
          type: string
          example: PARTNER
        metadata:
          description: Additional information to help identify the specific error case
          type: object
          properties:
            param:
              description: The name of the invalid parameter
              type: string
            reason:
              description:
                Optional human-readable information to explain why the parameter is
                invalid. Code must not rely on the content of this string.
              type: string
              example: "Expected format: YYYY-MM-DD"
          required:
            - param
        message:
          description: Human-readable message describing the error
          type: string
          example: A parameter in the request was not valid
      required:
        - code
        - metadata
        - message
    BadRequest:
      allOf:
        - $ref: "#/components/schemas/CommonErrorResponse"
        - properties:
            errors:
              type: array
              items:
                oneOf:
                  - $ref: "#/components/schemas/invalid-json"
                  - $ref: "#/components/schemas/missing-parameter"
                  - $ref: "#/components/schemas/invalid-parameter"
    invalid-credentials:
      title: invalid-credentials
      description: Authentication error - invalid credentials
      type: object
      properties:
        code:
          const: invalid-credentials
        originator:
          description: Additional information to help identify the error origin
          type: string
          example: PARTNER
        metadata:
          description:
            Additional information to help identify the specific error case
            (empty in this case)
          type: object
        message:
          description: Human-readable message describing the error
          type: string
          example: The supplied credentials are not valid
      required:
        - code
        - metadata
        - message
    InvalidCredentials:
      allOf:
        - $ref: "#/components/schemas/CommonErrorResponse"
        - properties:
            errors:
              type: array
              items:
                oneOf:
                  - $ref: "#/components/schemas/invalid-credentials"
    permission-denied:
      title: permission-denied
      description: Authorization error - permission denied
      type: object
      properties:
        code:
          const: permission-denied
        originator:
          description: Additional information to help identify the error origin
          type: string
          example: PARTNER
        metadata:
          description:
            Additional information to help identify the specific error case
            (empty in this case)
          type: object
        message:
          description: Human-readable message describing the error
          type: string
          example: The client is not permitted to perform this operation
      required:
        - code
        - metadata
        - message
    PermissionDenied:
      allOf:
        - $ref: "#/components/schemas/CommonErrorResponse"
        - properties:
            errors:
              type: array
              items:
                oneOf:
                  - $ref: "#/components/schemas/permission-denied"
    too-many-requests:
      title: too-many-requests
      description: Too many requests
      type: object
      properties:
        code:
          const: too-many-requests
        originator:
          description: Additional information to help identify the error origin
          type: string
          example: 'PARTNER'
        metadata:
          description:
            Additional information to help identify the specific error case
            (empty in this case)
          type: object
        message:
          description: Human-readable message describing the error
          type: string
          example: Request limit reached. Please try again later
      required:
        - code
        - metadata
        - message
    TooManyRequests:
      allOf:
        - $ref: "#/components/schemas/CommonErrorResponse"
        - properties:
            errors:
              type: array
              items:
                oneOf:
                  - $ref: "#/components/schemas/too-many-requests"
    partner-internal-server-error:
      title: internal-server-error [PP]
      description: Internal server error
      type: object
      properties:
        code:
          const: internal-server-error
        originator:
          description: Additional information to help identify the error origin
          type: string
          example: PARTNER
        metadata:
          description: Additional information to help identify the specific error case
          type: object
          properties:
            canRetry:
              description: Whether the partner believes the request can be retried
              type: boolean
              default: false
        message:
          description: Human-readable message describing the error
          type: string
          example:
            The server encountered an unexpected condition which prevented it from
            fulfilling the request
      required:
        - code
        - meta
        - message
    partner-code:
      title: Partner code
      description: >
        Code indicating the type of response the Bango Platform received
        from the partner.
      type: string
      example: service-unavailable
    partner-failure:
      title: partner-failure
      description: Partner failed
      type: object
      properties:
        code:
          const: partner-failure
        originator:
          description: Additional information to help identify the error origin
          type: string
          example: PARTNER
        metadata:
          description: Additional information to help identify the specific error case
          type: object
          properties:
            canRetry:
              description: Whether the request can be retried
              type: boolean
              default: true
            partnerCode:
              $ref: "#/components/schemas/partner-code"
        message:
          description: Human-readable message describing the error
          type: string
          example:
            The partner encountered an unexpected condition which prevented it from
            fulfilling the request
      required:
        - code
        - metadata
        - message
    partner-service-unavailable:
      title: service-unavailable [PP]
      description: Service is unavailable
      type: object
      properties:
        code:
          const: service-unavailable
        originator:
          description: Additional information to help identify the error origin
          type: string
          example: PARTNER
        metadata:
          description: Additional information to help identify the specific error case
          type: object
          properties:
            canRetry:
              description: Whether the partner believes the request can be retried
              type: boolean
              default: false
        message:
          description: Human-readable message describing the error
          type: string
          example:
            The service is undergoing maintenance and is not available. Please try
            again later
      required:
        - code
        - metadata
        - message
    PartnerServiceUnavailable:
      allOf:
        - $ref: "#/components/schemas/CommonErrorResponse"
        - properties:
            errors:
              type: array
              items:
                oneOf:
                  - $ref: "#/components/schemas/partner-service-unavailable"
  responses:
    BadRequestErrorResponse:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/BadRequest"
    InvalidCredentialsErrorResponse:
      description: |
        Authentication error - invalid credentials
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/InvalidCredentials"
    PermissionDeniedErrorResponse:
      description: >
        User is not authorized for this operation.


        This error occurs when you try to perform an operation on a resource, and you have permission to access the resource - but you don't have permission to perform the operation. For example, you may be authorized to `GET` the resource but not update it.


        (If you try to perform any operation on a resource you're not authorized to access, the API returns a 404 error.)
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/PermissionDenied"
    TooManyRequestsErrorResponse:
      description: >
        Request limit reached. The request was not processed.


        This error occurs when you send too many requests in a short period of time. You should pause before sending further requests.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/TooManyRequests"
    PartnerServiceUnavailableErrorResponse:
      description: Service unavailable
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/PartnerServiceUnavailable"
