Errors and Status Codes

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:

{
  "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:

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#

Check:

• active subscription exists
• plan includes the route you are calling
• usage has not exceeded the plan’s limit

I get 503 ASSESSMENT_PENDING#

This is usually a safe retry case for duplicate ingest races. Retry the exact same event after a short delay.