Error Codes¶
Standard error envelope:
json
{
"success": false,
"request_id": "uuid",
"data": null,
"error": {
"code": "ERROR_CODE",
"message": "Human-readable message.",
"details": []
}
}
Defined codes¶
| Code | Meaning |
|---|---|
INVALID_JSON |
Request body is not valid JSON |
MALFORMED_JSON |
JSON syntax cannot be parsed (detail: JSON_SYNTAX_ERROR with line/column when available) |
MALFORMED_XML |
XML syntax cannot be parsed or DOCTYPE was rejected (detail: XML_SYNTAX_ERROR) |
INVALID_FIELD_TYPE |
Field type mismatch; details include full path, expected_type, actual_type |
REQUIRED_FIELD_MISSING |
One or more required fields are missing |
UNKNOWN_FIELD |
Unknown JSON property or XML element |
INVALID_REQUEST |
Request is malformed |
VALIDATION_ERROR |
One or more contract validation errors (enum, datetime, range, mixed) |
VALIDATION_FAILED |
Legacy alias retained for some validation failures |
AUTHENTICATION_REQUIRED |
Authentication is required |
INVALID_CLIENT |
Client authentication failed |
INVALID_TOKEN |
Access token is invalid or expired |
INVALID_ACCESS_TOKEN |
Legacy alias retained for planned/older references |
UNSUPPORTED_GRANT_TYPE |
Token grant type is not supported |
INSUFFICIENT_SCOPE |
Token lacks required scope |
IDEMPOTENCY_CONFLICT |
Legacy alias; prefer IDEMPOTENCY_KEY_CONFLICT |
IDEMPOTENCY_KEY_REQUIRED |
Live endpoint missing required Idempotency-Key (HTTP 400) |
INVALID_IDEMPOTENCY_KEY |
Idempotency-Key empty, wrong length, invalid characters, whitespace, or duplicate header (HTTP 400) |
IDEMPOTENCY_KEY_CONFLICT |
Same key already used with a different canonical payload (HTTP 409) |
IDEMPOTENCY_REQUEST_IN_PROGRESS |
Active processing lease for the same key (HTTP 409, Retry-After: 2) |
REQUEST_ARCHIVE_UNAVAILABLE |
Required request archive insert/update unavailable (HTTP 503) |
IDEMPOTENCY_STORE_UNAVAILABLE |
Idempotency store unavailable (HTTP 503) |
PAYLOAD_TOO_LARGE |
Body exceeds configured limit |
UNSUPPORTED_MEDIA_TYPE |
Request Content-Type is not supported |
NOT_ACCEPTABLE |
Accept header is not supported |
METHOD_NOT_ALLOWED |
HTTP method not allowed |
ROUTE_NOT_FOUND |
Route does not exist |
NO_PROJECT_PROCESSED |
Structurally valid work-order request, but no project could be persisted on the live endpoint (HTTP 409) |
INTEGRATION_ACTOR_USER_NOT_FOUND |
Configured INTEGRATION_ACTOR_USER_ID does not match an existing user (HTTP 409) |
INTEGRATION_ACTOR_USER_INACTIVE |
Configured integration actor exists but is not active (HTTP 409) |
INTEGRATION_ACTOR_TENANT_MISMATCH |
Configured actor does not belong to the request tenant (HTTP 409) |
DATABASE_UNAVAILABLE |
MongoDB dependency unavailable (HTTP 503 on readiness, inbound persistence, inbound test reads, and outbound read endpoints) |
HEALTH_DETAILS_DISABLED |
Details endpoint is disabled |
INTERNAL_ERROR |
Unexpected internal failure |
Integration actor codes¶
Used by live POST /api/v1/inbound/work-orders when the configured integration identity cannot be used. These are not INTERNAL_ERROR. Responses never include the actor ObjectID, MongoDB URI, stack traces, or store internals.
| Code | HTTP | Meaning | Likely cause | Operator action |
|---|---|---|---|---|
INTEGRATION_ACTOR_USER_NOT_FOUND |
409 | No user document for INTEGRATION_ACTOR_USER_ID |
Installer/env points at a non-existent ObjectID (including a previously generated random ID) | Set --integration-actor-user-id to an existing active user and re-check |
INTEGRATION_ACTOR_USER_INACTIVE |
409 | User exists but status is not active |
Disabled/inactive directory user | Point config at an active integration user |
INTEGRATION_ACTOR_TENANT_MISMATCH |
409 | Actor company_id / organization_id do not match the request tenant |
Wrong actor for this tenant, or request tenant pair is wrong | Use an actor that belongs to the request tenant |
Tenant context codes¶
Used by inbound work orders, GET /api/v1/machine-events, and GET /api/v1/production-performance:
| Code | HTTP | Meaning |
|---|---|---|
TENANT_CONTEXT_REQUIRED |
400 | Neither request/query tenant pair nor configured DEFAULT_* defaults |
TENANT_CONTEXT_INCOMPLETE |
400 | Exactly one of company_id / organization_id supplied; env defaults are not applied |
INVALID_TENANT_CONTEXT |
400 | Provided tenant value is not a valid 24-character ObjectID |
Outbound read codes¶
| Code | HTTP | Meaning |
|---|---|---|
MACHINE_CODE_REQUIRED |
400 | machine_code query parameter missing |
MACHINE_NOT_FOUND |
404 | No machine for resolved tenant and machine_code |
PROJECT_CODE_REQUIRED |
400 | project_code query parameter missing |
PROJECT_NOT_FOUND |
404 | Project not found for tenant |
PRODUCTION_NOT_FOUND |
404 | Production not found in project |
PRODUCTION_STAGE_NOT_FOUND |
404 | Production stage not found |
PRODUCTION_CODE_REQUIRED |
400 | production_stage_code supplied without production_code |
INVALID_FILTER_DEPENDENCY |
400 | Filter dependency violated (stage requires production) |
INVALID_START_TIME |
400 | Malformed or unparsable start_time |
INVALID_END_TIME |
400 | Malformed or unparsable end_time |
INVALID_TIME_RANGE |
400 | Invalid time window (one-sided times, or start not before end) |
INVALID_LIMIT |
400 | limit outside 1–1000 |
INVALID_CURSOR |
400 | Cursor invalid or does not match current filters |
Validation detail codes (inbound work orders)¶
These appear in error.details[].code under VALIDATION_FAILED (HTTP 400) when the same request contains ambiguous structural duplicates:
| Code | Meaning |
|---|---|
DUPLICATE_PROJECT_CODE |
Same project_code repeated in one request |
DUPLICATE_PRODUCTION_CODE |
Same production_code repeated within one project |
DUPLICATE_PRODUCTION_STAGE_CODE |
Same production_stage_code repeated within one production |
DUPLICATE_MACHINE_CODE |
Same machine_code repeated within one stage |
DUPLICATE_EMPLOYEE_USERNAME |
Same username repeated within one stage |
Result / warning codes (inbound work orders)¶
These appear in successful live persistence responses under data.results[].warnings, and may also appear in NO_PROJECT_PROCESSED (409) details:
| Code | Meaning |
|---|---|
PROJECT_NAME_CONFLICT |
Existing project has the same project_code with a different project_name; project skipped |
MACHINE_NOT_FOUND |
Machine could not be resolved; production stage skipped |
EMPLOYEE_NOT_FOUND |
User could not be resolved; employee assignment skipped (stage continues) |
ALL_STAGES_SKIPPED |
All incoming stages for a production were skipped; production skipped |
ALL_PRODUCTIONS_SKIPPED |
All productions for a project were skipped; project skipped |
DATABASE_UNAVAILABLE is returned as HTTP 503 when MongoDB is unreachable during inbound live persistence (for example connection, server selection, or timeout failures). Client responses do not include internal MongoDB error text.
A 200 response from POST /api/v1/inbound/work-orders/test means the payload format and contract are valid. The test endpoint does not access MongoDB and does not return database-backed warning codes.