API Evangelist errors overlay for Pin Payments Cards API

overlay: 1.0.0
info:
  title: API Evangelist errors overlay for Pin Payments Cards API
  version: 1.0.0
extends: openapi/pin-payments-cards-api-openapi.yml
x-generated: '2026-10-21'
x-method: generated
x-source: https://pinpayments.com/developers/api-reference
x-rationale: The captured contract declares only success responses. Pin Payments documents a JSON error envelope
  and a set of universal errors (401, 404, 429, 500, 503) that may occur on any endpoint; this overlay adds them
  without mutating the original.
actions:
- target: $.components
  description: Add the documented error envelope (error, error_description, optional messages).
  update:
    schemas:
      PinError:
        type: object
        required:
        - error
        - error_description
        properties:
          error:
            type: string
            description: Machine-readable error code, e.g. not_found, rate_limited.
          error_description:
            type: string
          messages:
            type: array
            description: Per-parameter details, returned with 422 invalid_resource.
            items:
              type: object
              properties:
                code:
                  type: string
                message:
                  type: string
                param:
                  type: string
          charge_token:
            type: string
            description: Returned with some charge declines.
- target: $.paths['/cards'].post.responses
  description: Add the universal error responses documented for every endpoint (postCards).
  update:
    '401':
      description: 'unauthenticated: authentication failed (check API key).'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PinError'
    '404':
      description: 'not_found: the requested resource was not found.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PinError'
    '429':
      description: 'rate_limited: API use has exceeded rate limits.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PinError'
    '500':
      description: 'unknown_error: a non-specific error occurred at Pin Payments or an upstream provider.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PinError'
    '503':
      description: 'unavailable: the server cannot handle the request, typically during maintenance.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PinError'
- target: $.paths['/cards/{card_token}'].get.responses
  description: Add the universal error responses documented for every endpoint (getCardsByCardToken).
  update:
    '401':
      description: 'unauthenticated: authentication failed (check API key).'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PinError'
    '404':
      description: 'not_found: the requested resource was not found.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PinError'
    '429':
      description: 'rate_limited: API use has exceeded rate limits.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PinError'
    '500':
      description: 'unknown_error: a non-specific error occurred at Pin Payments or an upstream provider.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PinError'
    '503':
      description: 'unavailable: the server cannot handle the request, typically during maintenance.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PinError'