Errors and Validation.

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

HTTP status codes

Validation errors (422)

When a request fails validation, the API returns a 422 status with details about which fields failed and why:

{
  "message": "The title field is required.",
  "errors": {
    "fields.title": [
      "The title field is required."
    ],
    "fields.slug": [
      "The slug field format is invalid."
    ]
  }
}

These are production response examples. Local and test environments can include exception diagnostics on non-validation errors; clients should use HTTP status codes and validation fields instead of matching whole messages.

The errors object maps field names to arrays of error messages. Field names use dot notation for nested fields (e.g. fields.title for an entry field named title).

Authentication and permission errors (403)

Missing, invalid, revoked, or rotated API keys and origin mismatches return:

{
  "message": "Forbidden"
}

A valid key without the required ability or creator permission returns:

{
  "message": "This API key is not permitted to perform this action."
}

API keys do not have automatic expiry. Hosted authentication access tokens are separate credentials and cannot be used as API keys.

Upload validation

File uploads validate the file field against the platform's permitted types and maximum size. Missing files, invalid base64, disallowed file types, and files exceeding that limit return 422 with errors.file. PHP or the web server may reject oversized requests earlier with 413, before application validation runs.

Use Files API for multipart and base64 request formats. An API key with entry-write access alone cannot upload; it also needs files:write.

Not found errors (404)

{
  "message": "Not Found"
}

Rate limiting (429)

When you exceed the rate limit, the API returns:

{
  "message": "Too Many Requests"
}

The Retry-After header indicates how many seconds to wait before retrying. The defaults below are configurable and are disabled in local/test environments unless RATE_LIMITING_ENABLED=true.

Rate limits

Locale validation errors (400)

Invalid locale codes return 400. Read endpoints include the locale in the message; write validation may return the generic Bad Request:

{
  "message": "No locale found for [xx-XX]."
}

Suspended workspace errors (403)

Requests to a suspended workspace return:

{
  "message": "Workspace suspended."
}

See Workspace Suspension for details.

Common validation patterns

Related pages

• API Overview — Base URL, headers, and error handling.
• API Authentication — API keys and hosted authentication.
• Workspace Suspension — Suspension mechanics.