Error Codes

The Vivreal API uses standard HTTP status codes. This page covers the most common error responses and how to resolve them.

Error Response Format

All error responses use the standard envelope:

{
  "success": false,
  "data": null,
  "error": "A description of what went wrong."
}

Common Error Codes

Code	Name	Description
400	Bad Request	Missing or invalid query parameters, or the group account is frozen.
401	Unauthorized	Missing or invalid API key in the `Authorization` header.
402	Payment Required	Monthly API call or CDN bandwidth quota exceeded.
403	Forbidden	API key is valid but the group has been deactivated.
404	Not Found	The requested collection, object, or site does not exist.
500	Internal Server Error	Something went wrong on the server.

Detailed Guidance

400 Bad Request

The request is missing required parameters, or the group account is frozen. Common causes:

Missing collectionId on /tenant/collectionObjects
Missing siteId on /tenant/siteDetails
Missing type on /tenant/integrationObjects
Invalid JSON body on POST endpoints
The group account is frozen due to a billing issue

Resolution: Check the request parameters against the endpoint docs. If the error message mentions "frozen", contact your group admin to resolve the account status in the portal.

401 Unauthorized

Authentication failed. Common causes:

No Authorization header provided
Invalid or revoked API key
API key from a different group

Resolution: Verify your API key is correct. You can find it in the Vivreal portal under Group Settings.

402 Payment Required

Your group has exceeded its monthly usage quota. This can be triggered by either:

API call quota — You've used all of your monthly API requests
CDN bandwidth quota — You've consumed all of your monthly CDN bandwidth

Monthly quotas by tier:

Tier	API Calls/month	CDN Bandwidth/month
Free	1,000	1 GB
Basic	50,000	25 GB
Pro	500,000	100 GB
Pro Plus	2,000,000	500 GB

Quotas reset on the first of each month (UTC).

Resolution: Upgrade your tier for higher limits, or enable overage billing in Group Settings to continue making requests beyond your quota at metered rates. When overage billing is enabled, requests are never blocked — they are metered and billed at the end of the billing cycle.

403 Forbidden

The API key is valid but access is denied. Common causes:

The group has been deactivated

Resolution: Contact your group admin to resolve the account status.

404 Not Found

The requested resource doesn't exist. Common causes:

The collection or site ID is incorrect
The resource was deleted
The ID format is wrong (IDs are 24-character hex strings)

Resolution: Verify the IDs you're using. Use /tenant/collectionObjects with a known collection to confirm the ID is valid.

500 Internal Server Error

An unexpected error occurred on the server.

Resolution: Retry the request after a brief delay. If the error persists, check the Vivreal status page or contact support.