Record that the ProjectSuspended result code has been seen from real Vuforia

docs/source/differences-to-vws.rst

@@ -277,18 +277,27 @@ supported by the Flask/Docker backend.
 Other configurable result codes
 -------------------------------
 
-The mock also supports four other result codes which come from Vuforia's result codes table rather than from a response which a real database gave:
+The mock also supports four other result codes.
+``ProjectSuspended`` has been seen from a real database.
+The other three come from Vuforia's result codes table rather than from a response which a real database gave:
 
-.. admonition:: Unverified assumption
+.. admonition:: Unverified assumptions
+
+   :ref:`unverified-project-suspended`
 
    :ref:`unverified-additional-result-codes`
 
 
 * ``TargetQuotaReached`` is returned when adding a target to a
   :class:`mock_vws.database.CloudDatabase` which already contains
   ``target_quota`` targets.
-* ``ProjectSuspended`` is returned by VWS endpoints when a database uses the
+* ``ProjectSuspended`` is returned with status code 403 by every VWS endpoint
+  when a database uses the
   :attr:`mock_vws.states.States.PROJECT_SUSPENDED` state.
+  Real Vuforia has returned this result code for a database which passed its
+  monthly recognition threshold, but its status code, body and headers were
+  not recorded, and reads such as ``GET /targets`` and the database summary
+  kept working there.
 * ``ProjectHasNoApiAccess`` is returned by VWS endpoints when a database uses
   the :attr:`mock_vws.states.States.PROJECT_HAS_NO_API_ACCESS` state.
   This casing comes from Vuforia's result codes table, as no response from a

docs/source/unverified-behavior.rst

@@ -51,6 +51,26 @@ The mock models the limits separately for each group of endpoints, and applies t
 
 Sending more than the documented number of requests to a real database, and seeing what it returns, would verify this.
 
+.. _unverified-project-suspended:
+
+A suspended database
+--------------------
+
+:Category: temporarily-unverifiable
+:API: VWS Target API
+
+The mock returns a ``ProjectSuspended`` response with status code 403 from every VWS endpoint for a database in the :attr:`mock_vws.states.States.PROJECT_SUSPENDED` state.
+
+The result code string is confirmed.
+In August 2026 real Vuforia suspended one of the CI databases after it passed its monthly recognition threshold of 1000, and ``vws-python`` raised ``ProjectSuspendedError`` from the real response.
+Reads such as ``GET /targets`` and the database summary kept working, and writes such as ``POST /targets`` were rejected.
+
+The status code, body and headers of the real response were not recorded, and which endpoints reject requests was only partly observed.
+The mock rejects requests to every VWS endpoint, so it is stricter than the real service was seen to be.
+
+Driving a throwaway database past 1000 recognitions in a month with query requests, and recording the response from each VWS endpoint, would verify the rest.
+That is a deliberate one-off rather than a suite test because of the quota cost.
+
 .. _unverified-additional-result-codes:
 
 Additional result codes
@@ -59,7 +79,7 @@ Additional result codes
 :Category: never-attempted
 :API: VWS Target API
 
-``ProjectSuspended``, ``ProjectHasNoApiAccess``, ``TargetQuotaReached`` and ``TooManyRequests`` come from Vuforia's result codes table.
+``ProjectHasNoApiAccess``, ``TargetQuotaReached`` and ``TooManyRequests`` come from Vuforia's result codes table.
 No response from a real database in any of those states has been seen, which is why the mock's ``ProjectHasNoApiAccess`` casing is the table's casing rather than an observed one.
 
 A database put into each state by the Target Manager portal would verify these.