Errors and Status Codes

Common HTTP status codes and error patterns returned by VertexY.

Error model

VertexY returns standard HTTP status codes. Some errors also include a JSON body with:

statusCode
message
error
endpoint-specific details

Common status codes

200: request succeeded.
201: resource was created successfully.
400: request body, path, or query parameters were invalid.
401: authentication is missing, expired, or invalid.
402: the company has no usable subscription, or usage exceeded a hard limit.
403: the user is authenticated but does not have permission.
404: the requested resource does not exist.
409: the request conflicts with existing state, such as duplicate or mutually exclusive data.
429: too many requests in a short period.
500: unexpected internal server error.
503: temporary degradation, or a retryable pending state such as duplicate ingest waiting on the canonical result.

Authentication errors

401 Unauthorized: the access token is invalid, expired, or missing.
401 Session expired: the refresh token is invalid or expired.
403 Access denied: the authenticated user does not have the required role.

Billing and subscription errors

402 No active subscription found for company: the route requires an active paid plan.
402 Monthly usage limit exceeded...: the company crossed a hard usage ceiling for the current month.
400 Cannot subscribe to an inactive plan: the selected plan cannot be purchased.
409 Company already has a live subscription assignment in progress: an active or pending subscription already exists and conflicts with the request.

Ingest signature and replay errors

401 Missing ingest signature: the x-event-signature header was not sent.
401 Missing replay timestamp header: the x-event-timestamp header was not sent.
401 Missing replay nonce header: the x-event-nonce header was not sent.
401 Replay detected for nonce: the nonce was already used recently.
401 Invalid ingest signature: the signature does not match the raw request body and secret.

Ingest-specific edge cases

Duplicate event while canonical assessment is still being finalized

Possible response:

json

{
  "statusCode": 503,
  "message": "Assessment pending for duplicate event",
  "code": "ASSESSMENT_PENDING",
  "transactionId": "txn_100001"
}

Recommended client behavior:

wait briefly
retry with the same payload and same idempotencyKey

Rate limiting

The public ingest route may return:

plaintext

429 Too Many Requests

You may also see these headers:

X-RateLimit-Limit
X-RateLimit-Remaining
X-RateLimit-Reset

Validation examples

400 Invalid UUID: a field such as companyId, assessmentId, or planId is malformed.
400 Invalid currency: currency is not a 3-letter uppercase ISO code.
400 Invalid date: a timestamp or period field is malformed.

Troubleshooting checklist

I get `401` on `/events/ingest`

Check:

raw body is signed, not parsed JSON
correct secret for the company
timestamp is fresh
nonce is unique

I get `402 Payment Required`