Skip to main content

Error Handling

First-time workspace setup

Wire retry and escalation policies after Getting Started — Recommended Setup Sequence and a successful Swagger GET /listings smoke test (Authentication) — 401 / 403 usually mean missing setup steps 11–12 credentials or wrong environment, while business-rule 400s often trace to incomplete step 13 mapping (Property & Unit Mapping) or step 14 booking configuration. Finish Onboarding a New Property — Step 7 before treating error rates as integration defects. Guide pairing after go-live: Setup sequence after go-live (hub: API Reference — Setup sequence after go-live).

Finding your way in this guide

Start with Error Response Format and Common Error Codes, then Retry Strategy for enqueue and polling clients. Resolve 401 / 403 with Authentication; business-rule 400s after booking import map to Booking Lifecycle & Validations. Retry policy on POST /bookings enqueue is covered in Creating Bookings. Non-linear operator habits (Lockout catch-up, Pending manual receipt approval, Reject/revert mistaken receipts, Portfolio segmentation by tenant category, Notification row-click navigation, Payment alert to receivables triage, Confirmation alert triage, Finance debt receivables triage, Handling a Late Payment collections, Finance Income status drill-down, Cash flow forecast drill-down) have matching Related subsections below. Full pairing matrix: Error Handling section cross-reference · API Reference — API guide cross-reference.

The Vivin API uses standard HTTP status codes and returns structured JSON error responses.

Reproduce errors in Swagger

Integration Swagger on your API host lets you send real requests with Try it out and read the same JSON error envelope (statusCode, message, error) described below. See Authentication to authorize and open the integration UI.

Integration Swagger UI — listings operations expanded with Try it out after Bearer authorization

Error Response Format​

Pair with other Error Handling sections

Reproduce the same JSON envelope in Integration Swagger — Try requests in Swagger after Authentication. Full endpoint map: Error Handling section cross-reference.

{
  "statusCode": 400,
  "message": "Check-in date overlaps with an existing booking",
  "error": "Bad Request"
}
FieldTypeDescription
statusCodeintegerHTTP status code
messagestring or string[]Human-readable error description. May be an array for validation errors.
errorstringHTTP status text

Common Error Codes​

Pair with other Error Handling sections

404 on unknown externalId: Property & Unit Mapping. Async validation failures after enqueue: Booking Lifecycle & Validations. Full endpoint map: Error Handling section cross-reference.

Authentication Errors​

StatusMeaningResolution
401 UnauthorizedMissing or invalid Bearer tokenCheck your API key and Authorization header format
403 ForbiddenValid token but insufficient permissionsManagement UI shows You do not have permission to perform this action. for generic RBAC denials — see FAQ — Permission denied toast and Users and roles — Role Permissions. Integration clients: contact Vivin when the token is not scoped for the endpoint. Operator-only routes such as AI usage return 401 with integration Bearer keys — use Management session JWTs instead

Booking Submission Errors​

StatusMeaningResolution
400 Bad RequestValidation failed (missing fields, invalid dates, etc.)Read the message field for details on what to fix
404 Not FoundexternalId does not match any mapped listingVerify the listing mapping exists in Vivin
409 ConflictDates overlap with an existing bookingRe-fetch availability and retry with valid dates
422 Unprocessable EntityData is well-formed but violates a business rule (e.g. stay too short)Check booking windows and stay duration limits

Listing Errors​

StatusMeaningResolution
404 Not FoundThe requested externalId is not mapped to your platformConfirm the mapping with the property manager

Server Errors​

StatusMeaningResolution
500 Internal Server ErrorUnexpected server errorRetry after a short delay. If persistent, contact Vivin support
503 Service UnavailableAPI is temporarily unavailable (maintenance/deploy)Retry with exponential backoff

Validation Error Example​

When multiple fields fail validation, message may be an array:

{
  "statusCode": 400,
  "message": [
    "checkInDate must be a valid ISO 8601 date string",
    "tenant.email must be an email"
  ],
  "error": "Bad Request"
}

Retry Strategy​

Pair with other Error Handling sections

Booking idempotency with bookingId: Creating Bookings. Webhook delivery retries when your endpoint returns 5xx: Webhooks & Notifications. Full endpoint map: Error Handling section cross-reference.

For transient errors (5xx), use exponential backoff:

  1. Wait 1 second, retry
  2. Wait 2 seconds, retry
  3. Wait 4 seconds, retry
  4. Wait 8 seconds, retry
  5. After 4 retries, log the error and alert your team

For booking submissions, always include a bookingId to ensure idempotency - safe retries will not create duplicate bookings.

Do not retry 4xx errors

Client errors (400, 404, 409, 422) will not resolve on retry. Fix the request payload based on the error message before retrying.

Rate Limiting​

Pair with other Error Handling sections

429 backoff mirrors transient 5xx policy above. Operator JWT refresh failures: Management session. Full endpoint map: Error Handling section cross-reference.

If you exceed the API rate limits, you will receive:

{
  "statusCode": 429,
  "message": "Too many requests",
  "error": "Too Many Requests"
}

When rate-limited, respect the Retry-After header if present, or wait at least 60 seconds before retrying.

Error Handling section cross-reference​

Use this table when one error topic naturally leads into another API guide, operator UI, or downstream workflow — each row links to the docs you should read before or after wiring retry and recovery logic.

API topic / sectionPair with these docs
Error Response FormatTry requests in Swagger, Authentication
Common Error CodesProperty & Unit Mapping (404), Booking Lifecycle & Validations
Retry StrategyCreating Bookings, Webhooks & Notifications, Notifications — Payment overdue alerts → Handling a Late Payment — Step 1 (when enqueue succeeds but confirmation payment is still missing), Glossary — Credit note (payment reject/revert), Glossary — Invoiced floor (rent) (when correcting mistaken import receipts or repricing invoiced months)
Rate LimitingManagement session (JWT refresh vs integration keys), AI usage (management JWT only)

| Lockout catch-up after password recovery | Recoverable auth errors after sign-in recovery | Common Workflows — Lockout catch-up, Authentication Errors, Management session | | Pending manual receipt approval | Pending state is not an HTTP error | Common Workflows — Pending manual receipt approval, Creating Bookings, FAQ — Manual receipt still pending | | Reject/revert mistaken receipts | Receipt action validation errors | Common Workflows — Reject/revert mistaken receipts, Payment Allocation — Correcting mistaken receipts, Glossary — Credit note (payment reject/revert) | | Portfolio segmentation by tenant category | Segment-scoped permission errors | Common Workflows — Portfolio segmentation, Settings > Tenant categories, Glossary — Tenant category | | Notification row-click navigation | Retry policy vs alert triage | API Reference — Notification row-click navigation, Common Workflows — Notification row-click navigation, Notifications module — Notification row-click navigation | | Payment alert to receivables triage | 403 vs receivables row-click | API Reference — Payment alert to receivables triage, Common Workflows — Payment alert to receivables triage, Handling a Late Payment — Step 1 | | Confirmation alert triage | Validation errors vs confirmation alerts | API Reference — Confirmation alert triage, Common Workflows — Confirmation alert triage, Processing a New Booking — Step 5b | | Finance debt receivables triage | API errors vs Debt Aging reads | API Reference — Finance debt receivables triage, Common Workflows — Finance debt receivables triage, Finance module — Finance debt receivables triage | | Handling a Late Payment collections | Integration surface vs operator collections Steps 1–6 | | Finance Income status drill-down | Failed reads vs Income drill-down | API Reference — Finance Income status drill-down, Common Workflows — Finance Income status drill-down, FAQ — Finance Income status drill-down hub | | Cash flow forecast drill-down | Polling errors vs forecast modals | API Reference — Cash flow forecast drill-down, Common Workflows — Cash flow forecast drill-down, FAQ — Cash flow forecast drill-down hub |

Pair with other Error Handling guide sections

Related below links HTTP status codes and retry policy to setup, companion API guides, operator workflows, and escalation paths. Pair Setup sequence after go-live with Getting Started — Recommended Setup Sequence; pair Companion API guides with API Reference hub. Topic-to-guide pairing in sections above: Error Handling section cross-reference. Full hub matrix: API guide cross-reference.

Setup sequence after go-live​

Pair with other Error Handling guide sections

Complete Account Settings — Recommended setup order before partner traffic. Hub parity: API Reference — Setup sequence after go-live. Full pairing matrix: Error Handling section cross-reference · API guide cross-reference.

Documentation map & escalation​

Pair with other Error Handling guide sections

Documentation-map bullets pair with Introduction — Section cross-reference and FAQ — Section cross-reference. Full pairing matrix: Error Handling section cross-reference.

Companion API guides​

Pair with other Error Handling guide sections

Companion guides share Bearer authorization or error shapes with this page — start from API Reference hub. Full pairing matrix: Error Handling section cross-reference.

Upstream & downstream workflows​

Pair with other Error Handling guide sections

Workflow bullets pair with Common Workflows — Workflow cross-reference after partner traffic lands in the management app. Full pairing matrix: Error Handling section cross-reference.

Operator UI & settings​

Pair with other Error Handling guide sections

Operator UI rows validate the same inventory and permissions behind integration HTTP — pair with Account Settings — Tab cross-reference. Full pairing matrix: Error Handling section cross-reference.

Deeper concept reads​

Pair with other Error Handling guide sections

Concept reads pair with Concepts hub subsection index and Concept cross-reference. Full pairing matrix: Error Handling section cross-reference · API guide cross-reference.

Deeper workflow reads​

Pair with other Error Handling guide sections

Workflow reads pair with Common Workflows hub subsection index and Workflow cross-reference. Each workflow sub-guide also has its own Deeper API reads subsection with reciprocal companion API anchors — hub parity: API Reference — Deeper workflow reads. Full pairing matrix: Error Handling section cross-reference · API guide cross-reference.

Lockout catch-up after password recovery​

Pair with other Error Handling guide sections

Recoverable 401 on management JWT after lockout pairs with Management session authentication — partner Bearer keys are separate. Hub parity: Common Workflows — Lockout catch-up after password recovery. Full pairing matrix: error-handling-section-cross-reference · API guide cross-reference.

Pending manual receipt approval​

Pair with other Error Handling guide sections

Do not retry 201 enqueue as success for receipt approval — operators clear pending in Finance per Payment Allocation. Hub parity: Common Workflows — Pending manual receipt approval. Full pairing matrix: error-handling-section-cross-reference · API guide cross-reference.

Reject/revert mistaken receipts​

Pair with other Error Handling guide sections

Business-rule 400s on receipt actions pair with Payment Allocation — Correcting mistaken receipts. Hub parity: Common Workflows — Reject/revert mistaken receipts. Full pairing matrix: error-handling-section-cross-reference · API guide cross-reference.

Portfolio segmentation by tenant category​

Pair with other Error Handling guide sections

403 on segment-scoped operator routes may reflect tenant-category module rules — pair with Settings > Tenant categories. Hub parity: Common Workflows — Portfolio segmentation by tenant category. Full pairing matrix: error-handling-section-cross-reference · API guide cross-reference.

Notification row-click navigation​

Pair with other Error Handling guide sections

401/403 retry policy is distinct from /notifications row-click — fix Bearer authorization before operator alert triage on failed imports. Hub parity: API Reference — Notification row-click navigation. Full pairing matrix: Error Handling section cross-reference · API guide cross-reference.

Payment alert to receivables triage​

Pair with other Error Handling guide sections

Do not retry payment overdue collections on 403 alone — row-click into booking Transactions after permissions are restored. Hub parity: API Reference — Payment alert to receivables triage. Full pairing matrix: Error Handling section cross-reference · API guide cross-reference.

Confirmation alert triage​

Pair with other Error Handling guide sections

400 validation failures on POST /bookings are separate from Upcoming confirmation alert triage after successful enqueue. Hub parity: API Reference — Confirmation alert triage. Full pairing matrix: Error Handling section cross-reference · API guide cross-reference.

Finance debt receivables triage​

Pair with other Error Handling guide sections

Finance KPI 403s during receivables triage — restore operator permissions before Debt Aging Top debtors sign-off. Hub parity: API Reference — Finance debt receivables triage. Full pairing matrix: Error Handling section cross-reference · API guide cross-reference.

Handling a Late Payment collections​

Pair with other API Reference hub sections

Partner integration reads on Error Handling do not replace operator collections — payment overdue in-app rows still need Handling a Late Payment — Steps 1–6 after receivables triage. Hub parity: Common Workflows — Handling a Late Payment collections hub. Full pairing matrix: error-handling-section-cross-reference · API guide cross-reference.

Finance Income status drill-down​

Pair with other Error Handling guide sections

Failed Finance Overview reads do not replace Income segment-click habit — retry management JWT before month-end segment modals. Hub parity: API Reference — Finance Income status drill-down. Full pairing matrix: Error Handling section cross-reference · API guide cross-reference.

Cash flow forecast drill-down​

Pair with other Error Handling guide sections

Polling fallback after webhook 5xx — Cash flow forecast bar-click still requires operator Finance access, not integration Bearer keys. Hub parity: API Reference — Cash flow forecast drill-down. Full pairing matrix: Error Handling section cross-reference · API guide cross-reference.

Key glossary terms​

Pair with other Error Handling guide sections

Glossary rows pair with Glossary cluster cross-reference and receipt-dispute workflows. Full pairing matrix: Error Handling section cross-reference.

Module documentation hubs​

Pair with other Error Handling guide sections

Module hubs pair with Modules — Module cross-reference for screen-by-screen operator follow-up. Full pairing matrix: Error Handling section cross-reference.

  • Listings module — Property wizard, Channels tab, and unit management (hub)
  • Finance module — Portfolio ledgers with payment approval and deposit settlement (hub)
  • Tenants module — Tenant directory and profile sidebars for imported stays (hub)
  • Sales module — Portfolio availability and channel manager connections (hub)
  • Audit module — Portfolio-wide Manual Blocks and Discounts contract-value review (hub)
  • Dashboard module — Post-login KPI snapshot with bell notification triage (hub)
  • Analytics module — Month-range portfolio KPI charts with rankings and heatmaps (hub)
  • Properties workspace — Legacy /properties URL redirects into Listings (hub)
  • Booking engine details — Rich marketplace payload editor via the Full integration pill (hub)
  • Utilities module — Bills Included ceiling model and tenant overage charges (hub)
  • Operations module — Maintenance tickets, cash flows, and check-in/out coordination (hub)
  • Inbox module — Portfolio-wide WhatsApp workspace (hub)
  • Notifications module — Full /notifications history with search and filters (hub); Payment overdue alerts when retry success still leaves unpaid schedules
  • AI Chat module — Vivin-internal AI Assistant using Landlord MCP tools (hub)
  • Account Settings — Workspace-wide financial policies, templates, integrations, and operational defaults (hub)