openapi: 3.1.0
# Canonical path: ./common/responses.yaml
info:
  title: Quub Exchange - Common Responses
  version: 2.2.0
  description: |
    Shared response templates for success and error outcomes across all Quub APIs.
    Each response references schemas from ./common/errors.yaml for consistency.
  license:
    name: Proprietary
    url: https://quub.exchange/license

servers:
  - url: https://api.quub.exchange
    description: Placeholder (this file contains only reusable components)

paths: {} # This file contains only reusable components

components:
  responses:
    # ==========================================================================
    # SUCCESS RESPONSES
    # ==========================================================================
    OkObjectResponse:
      description: Successful single-object response
      content:
        application/json:
          schema:
            type: object
            properties:
              data:
                type: object
                description: Resource data object

    OkListResponse:
      description: Paginated list of resources
      content:
        application/json:
          schema:
            allOf:
              - $ref: "./pagination.yaml#/components/schemas/PageResponse"
              - type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object

    CreatedResponse:
      description: Resource created successfully (201)
      content:
        application/json:
          schema:
            type: object
            properties:
              data:
                type: object
                description: Created resource

    NoContentResponse:
      description: Successful operation with no response body (204)

    AcceptedResponse:
      description: Accepted for asynchronous processing (202)
      content:
        application/json:
          schema:
            type: object
            properties:
              taskId:
                type: string
                example: "task_123abc"
              status:
                type: string
                enum: [PENDING, PROCESSING, COMPLETED]
                example: "PENDING"

    # ==========================================================================
    # STANDARD ERROR RESPONSES
    # ==========================================================================
    BadRequest:
      description: Invalid request payload or query parameters (400)
      content:
        application/json:
          schema:
            $ref: "./errors.yaml#/components/schemas/Problem"
          example:
            type: "https://docs.quub.exchange/problems/bad-request"
            title: "Bad Request"
            status: 400
            detail: "Invalid input parameters"
            code: "BAD_REQUEST"

    Unauthorized:
      description: Missing or invalid authentication credentials (401)
      content:
        application/json:
          schema:
            $ref: "./errors.yaml#/components/schemas/Problem"
          example:
            type: "https://docs.quub.exchange/problems/unauthorized"
            title: "Unauthorized"
            status: 401
            detail: "Authentication required"
            code: "UNAUTHORIZED"

    Forbidden:
      description: Insufficient permissions (403)
      content:
        application/json:
          schema:
            $ref: "./errors.yaml#/components/schemas/Problem"
          example:
            type: "https://docs.quub.exchange/problems/forbidden"
            title: "Forbidden"
            status: 403
            detail: "Insufficient permissions"
            code: "FORBIDDEN"

    NotFound:
      description: Resource not found (404)
      content:
        application/json:
          schema:
            $ref: "./errors.yaml#/components/schemas/Problem"
          example:
            type: "https://docs.quub.exchange/problems/not-found"
            title: "Not Found"
            status: 404
            detail: "Resource not found"
            code: "NOT_FOUND"

    Conflict:
      description: Resource already exists or version conflict (409)
      content:
        application/json:
          schema:
            $ref: "./errors.yaml#/components/schemas/Problem"
          example:
            type: "https://docs.quub.exchange/problems/conflict"
            title: "Conflict"
            status: 409
            detail: "Resource already exists"
            code: "CONFLICT"

    ValidationError:
      description: Request validation failed (422)
      content:
        application/json:
          schema:
            $ref: "./errors.yaml#/components/schemas/ValidationError"
          example:
            type: "https://docs.quub.exchange/problems/validation-error"
            title: "Validation Error"
            status: 422
            detail: "Request validation failed"
            code: "VALIDATION_ERROR"
            errors:
              - field: "email"
                message: "Invalid email format"

    TooManyRequests:
      description: Rate limit exceeded (429)
      content:
        application/json:
          schema:
            $ref: "./errors.yaml#/components/schemas/Problem"
          example:
            type: "https://docs.quub.exchange/problems/rate-limit"
            title: "Too Many Requests"
            status: 429
            detail: "Rate limit exceeded"
            code: "RATE_LIMIT_EXCEEDED"

    InternalServerError:
      description: Unexpected internal error (500)
      content:
        application/json:
          schema:
            $ref: "./errors.yaml#/components/schemas/Problem"
          example:
            type: "https://docs.quub.exchange/problems/internal-error"
            title: "Internal Server Error"
            status: 500
            detail: "An unexpected error occurred"
            code: "INTERNAL_ERROR"

    ServiceUnavailable:
      description: Service temporarily unavailable (503)
      content:
        application/json:
          schema:
            $ref: "./errors.yaml#/components/schemas/Problem"
          example:
            type: "https://docs.quub.exchange/problems/service-unavailable"
            title: "Service Unavailable"
            status: 503
            detail: "Service temporarily unavailable"
            code: "SERVICE_UNAVAILABLE"

    # ==========================================================================
    # DOMAIN-SPECIFIC ERROR RESPONSES
    # ==========================================================================
    OrgMismatch:
      description: Organization ID mismatch between path and resource (400)
      content:
        application/json:
          schema:
            $ref: "./errors.yaml#/components/schemas/OrgMismatchError"
          example:
            type: "https://docs.quub.exchange/problems/org-mismatch"
            title: "Organization Mismatch"
            status: 400
            detail: "Resource does not belong to the specified organization"
            code: "ORG_MISMATCH"

    OrgUnverified:
      description: Organization not yet verified (403)
      content:
        application/json:
          schema:
            $ref: "./errors.yaml#/components/schemas/OrgUnverifiedError"
          example:
            type: "https://docs.quub.exchange/problems/org-unverified"
            title: "Organization Not Verified"
            status: 403
            detail: "Organization verification required"
            code: "ORG_UNVERIFIED"

    DnssecRequired:
      description: DNSSEC required but not detected (400)
      content:
        application/json:
          schema:
            $ref: "./errors.yaml#/components/schemas/DnssecRequiredError"
          example:
            type: "https://docs.quub.exchange/problems/dnssec-required"
            title: "DNSSEC Required"
            status: 400
            detail: "DNSSEC required for verified domains"
            code: "DNSSEC_REQUIRED"

    WebhookDomainMismatch:
      description: Webhook URL not under verified domain (400)
      content:
        application/json:
          schema:
            $ref: "./errors.yaml#/components/schemas/WebhookDomainMismatchError"
          example:
            type: "https://docs.quub.exchange/problems/webhook-domain-mismatch"
            title: "Webhook Domain Mismatch"
            status: 400
            detail: "Webhook URL domain must match verified organization domain"
            code: "WEBHOOK_DOMAIN_MISMATCH"