Pin Payments · OpenAPI Overlay 1.0.0

API Evangelist errors overlay for Pin Payments Customers API

12 actions 12 updates update extends openapi/pin-payments-customers-api-openapi.yml
Generated by API Evangelist Written by API Evangelist tooling for Pin Payments's API. It is a proposal applied on top of the contract, not a document Pin Payments publishes.
View Overlay File View on GitHub Overlay Specification

What the actions change

401404429500503schemas

Targets 12

$.components
$.paths['/customers'].post.responses
$.paths['/customers'].get.responses
$.paths['/customers/{customer_token}'].get.responses
$.paths['/customers/{customer_token}'].put.responses
$.paths['/customers/{customer_token}'].delete.responses
$.paths['/customers/{customer_token}/charges'].get.responses
$.paths['/customers/{customer_token}/cards'].get.responses
$.paths['/customers/{customer_token}/cards'].post.responses
$.paths['/customers/{customer_token}/cards/{card_token}'].delete.responses
$.paths['/customers/{customer_token}/subscriptions'].get.responses
$.paths['/customers/{customer_token}/subscriptions/{sub_token}'].delete.responses

OpenAPI Overlay

Raw ↑ 
overlay: 1.0.0
info:
  title: API Evangelist errors overlay for Pin Payments Customers API
  version: 1.0.0
extends: openapi/pin-payments-customers-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['/customers'].post.responses
  description: Add the universal error responses documented for every endpoint (postCustomers).
  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['/customers'].get.responses
  description: Add the universal error responses documented for every endpoint (getCustomers).
  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['/customers/{customer_token}'].get.responses
  description: Add the universal error responses documented for every endpoint (getCustomersByCustomerToken).
  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['/customers/{customer_token}'].put.responses
  description: Add the universal error responses documented for every endpoint (putCustomersByCustomerToken).
  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['/customers/{customer_token}'].delete.responses
  description: Add the universal error responses documented for every endpoint (deleteCustomersByCustomerToken).
  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['/customers/{customer_token}/charges'].get.responses
  description: Add the universal error responses documented for every endpoint (getCustomersByCustomerTokenCharges).
  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['/customers/{customer_token}/cards'].get.responses
  description: Add the universal error responses documented for every endpoint (getCustomersByCustomerTokenCards).
  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['/customers/{customer_token}/cards'].post.responses
  description: Add the universal error responses documented for every endpoint (postCustomersByCustomerTokenCards).
  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['/customers/{customer_token}/cards/{card_token}'].delete.responses
  description: Add the universal error responses documented for every endpoint (deleteCustomersByCustomerTokenCardsByCardToken).
  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['/customers/{customer_token}/subscriptions'].get.responses
  description: Add the universal error responses documented for every endpoint (getCustomersByCustomerTokenSubscriptions).
  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['/customers/{customer_token}/subscriptions/{sub_token}'].delete.responses
  description: Add the universal error responses documented for every endpoint (deleteCustomersByCustomerTokenSubscriptionsBySubToken).
  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'

Work with this as data

Every overlay here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for openapi overlays

4 MCP tools reach this
  • find_overlaysBrowse and filter every overlay in the catalog.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This overlay 
curl "https://apis.io/api/v1/overlays/pin-payments-customers-errors-overlay"
All openapi overlays 
curl "https://apis.io/api/v1/overlays?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.