Errors & status codes
How to interpret API errors, authentication failures, validation problems, conflicts, and recoverable workflow failures.
OmniValVMS APIs use standard HTTP status codes with structured error responses. The exact response body varies by endpoint and failure type, so clients should handle errors by status code first, then display the server-provided message when it is safe and actionable.
Status code guide
| Status | Meaning | What to do |
|---|---|---|
200 / 201 | Request succeeded | Continue with the returned data. |
400 | Validation or business-rule failure | Show the message, correct the request, and retry only after fixing input. |
401 | Missing, expired, or invalid token | Refresh the token. Retry once only for reads or clearly idempotent operations; for P0 writes, reload state/history first. |
403 | Authenticated but not allowed | Do not retry automatically; confirm role, client scope, or ownership. |
404 | Resource not found or not visible to caller | Confirm IDs and client/vendor scope. |
409 | State conflict or duplicate action | Refresh the resource and follow the current state machine. |
422 | Request understood but not processable | Correct domain data such as missing order fields or invalid transition inputs. |
429 | Too many requests | Back off before retrying. |
500 | Unexpected server error | Retry cautiously if the action is safe; otherwise contact support with correlation details. |
Order activation, vendor assignment, QC/revision, UCDP/EAD submission, and payment processing are protected flows. Before retrying after an unclear failure, reload the order and check history so you do not duplicate a charge, assignment, submission, or audit-sensitive action.
Authentication failures
When a request fails with 401, use the refresh-token flow. For reads and
clearly idempotent operations, retry once after refresh:
If refresh fails, send the user through sign-in again:
For state-changing P0 actions — activation, assignment, QC/revision, payments, and agency submissions — do not automatically replay the write after refreshing. Reload the order, check history, and confirm the prior attempt did not complete.
Validation failures
Validation errors usually mean required data is missing, formatted incorrectly, or violates the current workflow state. Common examples:
- Creating an order without required loan, property, product, or contact data.
- Activating a draft order before it has enough information.
- Assigning a vendor who is not eligible for the product, region, or client panel.
- Collecting payment before the report has been delivered and approved.
For order creation and activation, use the order endpoints as the authoritative contract:
| Flow | Endpoint |
|---|---|
| Create order | |
| Activate draft order | |
| Update order status |
Conflicts and state-machine errors
Orders follow a state machine. A request may be rejected if the order has moved since you loaded it or if the requested transition skips required steps.
Reload the order
Fetch the latest order state before deciding whether to retry or present a different action to the user.
Read the history
Retry only if safe
Retry idempotent reads freely. Retry writes only when you can prove the previous attempt did not complete or when the endpoint is explicitly safe to repeat.
User-facing error messages
Good error handling tells a busy operator what happened and what to do next.
| Bad | Better |
|---|---|
Error occurred | The vendor is no longer eligible for this order. Choose another vendor or update the panel. |
Payment failed | Payment was not collected. Check payment history, verify the payment method, then retry only if no charge was recorded. |
Unauthorized | Your session expired. Sign in again to continue. |
Support checklist
When escalation is needed, include:
- Client ID and order ID
- User who attempted the action
- Timestamp and timezone
- Endpoint and operation attempted
- HTTP status code and safe error message
- Whether the user retried, and what the current order history shows