WedStay
info@thewedstay.comGet the iOS App

Subscribe to our newsletter

By subscribing, you agree to receive emails and texts from WedStay. Unsubscribe anytime.

For Everyone

  • About Us
  • Is WedStay Legit?
  • How It Works
  • Download App
  • Blog
  • Reviews
  • FAQs
  • Terms
  • Privacy
  • Contact
  • We're Hiring!
  • Creator Program
  • Sitemap
  • Developers & API

For Couples

  • Wedding Venues
  • Wedding Venue Buyout
  • Wedding House Rentals
  • How WedStay Works
  • WedStay One Wedding Website
  • Wedding Venue Finder
  • Wedding Quizzes
  • Venue Style Quiz
  • How Venue Matcher Works
  • 2026 Wedding Trends
  • Viral Wedding Estates
  • Wedding Vendors
  • Wedding Inspiration
  • Non-Traditional Weddings
  • Wedding Weekend Experience
  • Wedding Planning Checklist Tool
  • Planning Tools
  • WedStay-Style Weddings
  • Venue Cost Calculator
  • Wedding Weekend Cost Calculator
  • Wedding Financing

For Property Owners

  • Submit Your Property
  • Wedding Industry Insights
  • Revenue Opportunities
  • WedStay Operating System
  • Property Transformation
  • Effortless Hosting
  • Top Wedding Trends

For Vendors

  • Join The WedStay Collective
  • Wedding Vendors
  • Wedding Photographers
  • The Ultimate Wedding Vendor Guide: A Former Bride's Tell-All

© 2026 WedStay. All rights reserved.

This site is not affiliated with or endorsed by Airbnb.

    WedStay Developers
    WedStay Developers
    API Referencethewedstay.com

    Getting Started

    WedStay APIQuickstart

    Endpoints

    VenuesVendorsPricingBlogInquiries

    Reference

    ErrorsRate LimitsChangelog

    Integrations

    MCP ServerChatGPT ActionBuilding AI-Powered Widgets

    Errors

    Error response format, error types, and HTTP status codes used by the WedStay API.

    Error Reference

    All API errors follow a consistent envelope format. Use the type and code fields for programmatic error handling, and message for display to users.

    Error format

    {
      "error": {
        "type": "invalid_request_error",
        "code": "sms_consent_required",
        "message": "sms_consent is required and must be true or false. Ask the couple: 'OK if WedStay texts you about this request?' Send true only if they said yes.",
        "param": "sms_consent",
        "request_id": "req_abc123def456",
        "doc_url": "https://www.thewedstay.com/developers/errors#sms_consent_required"
      }
    }
    FieldTypeDescription
    typestringError category (see table below)
    codestringSpecific error code for programmatic handling
    messagestringHuman readable description
    paramstringThe request field at fault, when there is one
    request_idstringUnique request identifier for support
    doc_urlstringThis page, at the code's own anchor: https://www.thewedstay.com/developers/errors#<code>
    hintstringWhat to do next, when there is a clear next step

    Error types

    TypeHTTP StatusDescription
    invalid_request_error400The request is missing something it must carry
    validation_error400A field has an invalid value or failed validation
    authentication_error401Invalid or missing API key
    not_found404The requested resource or route does not exist
    conflict409The request clashes with an earlier one (idempotency)
    rate_limit_exceeded429Too many requests, slow down
    internal_error500, 503Something went wrong on our end

    Error codes

    invalid_request_error (400)

    CodeDescription
    sms_consent_requiredAn inquiry (POST /api/v1/inquiries/venue or /vendor) without a boolean sms_consent. Ask the couple whether WedStay may text them and send true or false. No lead is written

    validation_error (400)

    CodeDescription
    invalid_parametersOne or more fields failed validation; message names each field and the problem
    invalid_jsonThe request body is not valid JSON
    invalid_cursorThe pagination cursor is not one this API issued
    invalid_idThe id path parameter is not a valid UUID
    invalid_slugThe slug path parameter has characters a slug cannot have
    invalid_regionThe pricing region is not recognized; message lists the valid ones
    invalid_seasonseason is not peak, shoulder or off
    invalid_event_typeevent_type is not weekday or weekend
    invalid_event_guestsevent_guests is outside the allowed range
    invalid_overnight_guestsovernight_guests is outside the allowed range
    invalid_nightsnights is outside the allowed range
    invalid_venue_typevenue_type is not one of the listed types
    affiliate_only_vendorThe vendor is listed through an affiliate link and takes no inquiries. Use its affiliate_link instead

    authentication_error (401)

    CodeDescription
    missing_api_keyNo Authorization: Bearer header or X-WedStay-Key header. Request a key by emailing info@thewedstay.com (keys are issued manually during the beta), or use the keyless MCP server
    invalid_api_keyThe API key is not valid or has been revoked

    not_found (404)

    CodeDescription
    venue_not_foundNo published venue has that slug. Use the full slug from search results, URL encoded
    vendor_not_foundNo listed vendor has that slug
    blog_post_not_foundNo published blog post has that slug
    inspiration_photo_not_foundNo inspiration photo has that id
    route_not_foundNo API route matches the path. Public endpoints live under /api/v1 (OpenAPI)

    conflict (409)

    Returned by the inquiry endpoints only.

    CodeDescription
    idempotency_conflictThis X-Idempotency-Key was already used with a different request body. Use a new key for a new inquiry
    idempotency_in_progressA request with this X-Idempotency-Key is still being processed. Retry in a few seconds

    rate_limit_exceeded (429)

    CodeDescription
    rate_limit_exceededYour key's per minute or daily limit is used up. Wait for Retry-After
    venue_detail_rate_limit_exceededThe free tier's 20 venue detail lookups per day are used up
    inquiry_rate_limit_exceededYour key's daily inquiry limit is used up

    See Rate limits for the limits and headers.

    internal_error (500, 503)

    CodeDescription
    internal_errorAn unexpected error occurred. Retry once; if it persists, contact support with the request_id
    database_errorA database read failed. Retry with backoff
    insert_failedThe inquiry could not be saved. Retry; the idempotency key keeps a retry from creating a second lead
    knowledge_unavailableThe knowledge store is not available (503). Retry later

    HTTP status codes

    StatusMeaning
    200Success
    201Created (inquiry submitted)
    400Bad request
    401Unauthorized
    404Not found
    409Conflict
    429Rate limited
    500Internal server error
    503Service unavailable

    Handling errors

    const response = await fetch('https://www.thewedstay.com/api/v1/venues', {
      headers: { Authorization: 'Bearer ws_live_...' },
    })
     
    if (!response.ok) {
      const { error } = await response.json()
     
      switch (error.type) {
        case 'rate_limit_exceeded':
          // Wait and retry
          const retryAfter = response.headers.get('Retry-After')
          break
        case 'authentication_error':
          // Check your API key
          break
        default:
          console.error(`API error: ${error.code} - ${error.message}`)
      }
    }

    Previous

    Inquiries

    Next

    Rate Limits

    On this page

    Error ReferenceError formatError typesError codesinvalid_request_error (400)validation_error (400)authentication_error (401)not_found (404)conflict (409)rate_limit_exceeded (429)internal_error (500, 503)HTTP status codesHandling errors