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. Habit-specific shortcuts live under Related below.

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.

{
  "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, or Listing not available when rent is unusable: Property & Unit Mapping, Usable rent required. Async validation failures after enqueue: Booking Lifecycle & Validations.

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 platform, or the unit has no usable positive rent (Listing not available)Confirm the mapping, then Rent Value — Usable rent required

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.

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.

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 the endpoints and fields above. Related integrator pages are linked inline where useful.

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.

Setup sequence after go-live​

Pair with other Error Handling guide sections

Complete Account Settings — Recommended setup order before partner traffic.

Documentation map & escalation​

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.

Upstream & downstream workflows​

Operator UI & settings​

Deeper concept reads​

  • Integrations & Distribution — Channel context when 404/409 errors trace to mapping or sync
  • Payment allocation — Layer 1/Layer 2 receipt errors when confirmation payments fail after a successful enqueue
  • Booking Lifecycle — Operator computed statuses when HTTP errors differ from integration queue states
  • Deep Links — Bookmarkable module routes when retrying after mapping or availability fixes
  • Tenant Portal — Tenant recovery screens when portal bootstrap fails after a partner import creates a booking
  • FAQ — Tenant contract signing blocked — No PDF yet, mandatory Your Details gates, category locks, or Lease purpose; portal signing vs paper upload on Contract Info

Deeper workflow reads​

See Upstream & downstream workflows above for the same guides.

Operator habit hubs​

Day-to-day operator habits (lockout catch-up, pending receipts, payment triage, handoffs, and related playbooks) live on the Common Workflows habit hub.

Deep-link anchors for habit hubs

Lockout catch-up after password recovery​

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​

Key glossary terms​

Module documentation hubs​

Pair with other Error Handling guide sections

for screen-by-screen operator follow-up.

  • 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 — AI Assistant using Landlord MCP tools (hub)
  • Account Settings — Workspace-wide financial policies, templates, integrations, and operational defaults (hub)