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
| Field | Type | Description |
|---|---|---|
type | string | Error category (see table below) |
code | string | Specific error code for programmatic handling |
message | string | Human readable description |
param | string | The request field at fault, when there is one |
request_id | string | Unique request identifier for support |
doc_url | string | This page, at the code's own anchor: https://www.thewedstay.com/developers/errors#<code> |
hint | string | What to do next, when there is a clear next step |
Error types
| Type | HTTP Status | Description |
|---|---|---|
invalid_request_error | 400 | The request is missing something it must carry |
validation_error | 400 | A field has an invalid value or failed validation |
authentication_error | 401 | Invalid or missing API key |
not_found | 404 | The requested resource or route does not exist |
conflict | 409 | The request clashes with an earlier one (idempotency) |
rate_limit_exceeded | 429 | Too many requests, slow down |
internal_error | 500, 503 | Something went wrong on our end |
Error codes
invalid_request_error (400)
| Code | Description |
|---|---|
sms_consent_required | An 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)
| Code | Description |
|---|---|
invalid_parameters | One or more fields failed validation; message names each field and the problem |
invalid_json | The request body is not valid JSON |
invalid_cursor | The pagination cursor is not one this API issued |
invalid_id | The id path parameter is not a valid UUID |
invalid_slug | The slug path parameter has characters a slug cannot have |
invalid_region | The pricing region is not recognized; message lists the valid ones |
invalid_season | season is not peak, shoulder or off |
invalid_event_type | event_type is not weekday or weekend |
invalid_event_guests | event_guests is outside the allowed range |
invalid_overnight_guests | overnight_guests is outside the allowed range |
invalid_nights | nights is outside the allowed range |
invalid_venue_type | venue_type is not one of the listed types |
affiliate_only_vendor | The vendor is listed through an affiliate link and takes no inquiries. Use its affiliate_link instead |
authentication_error (401)
| Code | Description |
|---|---|
missing_api_key | No 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_key | The API key is not valid or has been revoked |
not_found (404)
| Code | Description |
|---|---|
venue_not_found | No published venue has that slug. Use the full slug from search results, URL encoded |
vendor_not_found | No listed vendor has that slug |
blog_post_not_found | No published blog post has that slug |
inspiration_photo_not_found | No inspiration photo has that id |
route_not_found | No API route matches the path. Public endpoints live under /api/v1 (OpenAPI) |
conflict (409)
Returned by the inquiry endpoints only.
| Code | Description |
|---|---|
idempotency_conflict | This X-Idempotency-Key was already used with a different request body. Use a new key for a new inquiry |
idempotency_in_progress | A request with this X-Idempotency-Key is still being processed. Retry in a few seconds |
rate_limit_exceeded (429)
| Code | Description |
|---|---|
rate_limit_exceeded | Your key's per minute or daily limit is used up. Wait for Retry-After |
venue_detail_rate_limit_exceeded | The free tier's 20 venue detail lookups per day are used up |
inquiry_rate_limit_exceeded | Your key's daily inquiry limit is used up |
See Rate limits for the limits and headers.
internal_error (500, 503)
| Code | Description |
|---|---|
internal_error | An unexpected error occurred. Retry once; if it persists, contact support with the request_id |
database_error | A database read failed. Retry with backoff |
insert_failed | The inquiry could not be saved. Retry; the idempotency key keeps a retry from creating a second lead |
knowledge_unavailable | The knowledge store is not available (503). Retry later |
HTTP status codes
| Status | Meaning |
|---|---|
200 | Success |
201 | Created (inquiry submitted) |
400 | Bad request |
401 | Unauthorized |
404 | Not found |
409 | Conflict |
429 | Rate limited |
500 | Internal server error |
503 | Service unavailable |