Monitoring Codes

{/ AUTOGENERATED — do not edit by hand. Source: erp-integration-api packages/erp-utils/src/monitoring/snapshots/monitoring-codes.json Regenerate: npm run update-monitoring-codes /}

Monitoring Codes

Every monitoring event carries a code and a level. The code says what happened; the level says how much you should care. Both are filterable in the Integration Hub's Monitoring tab and through the events API.

There are 80 codes. You are most likely here because you saw one in a failed event — find it below.

tip

A code's level is fixed. That is what makes alert rules scoped to _error_ or _warning_ predictable — see Alerting.

Error

Something failed and the event did not do what it was meant to do. These are what the default alert rules watch.

Code	What it means
ATTACHMENT_NOT_FOUND	The file no longer exists — it was removed between the event and the delivery
ATTRIBUTE_TYPE_MISMATCH	An attribute value did not match the type declared in the entity schema
DEPRECATED_ENDPOINT	This endpoint version is deprecated
DIRECT_ENTITY_NOT_ALLOWED	The entity is not permitted by the use case entity allowlist
DIRECT_PAYLOAD_INVALID	The direct mode payload failed validation against the versioned payload schema
DIRECT_VERSION_UNSUPPORTED	The direct mode payload version is not supported by the platform
ENTITY_REFERENCE_NOT_FOUND	A direct-by-id entity reference points at an entity that does not exist or has a different schema
EVENT_NOT_CONFIGURED	No mapping configuration found for this event type
EXTERNAL_API_ERROR	An external API returned an error
EXTERNAL_ERROR	An error span pushed by an external system (e.g. your integration middleware) via the external monitoring events endpoint. epilot assigns the code from the span's level; the middleware never sends one.
FAN_OUT_INVALID_RESULT	The split expression returned something other than a list, so no deliveries could be created — see split_expression_result_type
FILE_EXTRACTION_FAILED	Failed to extract file from the request
FILE_FETCH_FAILED	The file could not be fetched from epilot before it could be uploaded
FILE_PROXY_UPLOAD_FAILED	A file upload failed terminally, or every delivery attempt was exhausted
FILE_TOO_LARGE	The file exceeds the maximum size configured on the upload use case
INTEGRATION_NOT_FOUND	The inbound event referenced an integration_id that does not exist in the calling token's organization. Check the integration id and that the token belongs to the same org.
INVALID_METER_READING_ATTRIBUTES	Meter reading has invalid attributes
MALFORMED_PAYLOAD	The event payload could not be parsed (malformed JSON)
MAPPING_EXPRESSION_FAILED	A mapping expression failed to evaluate
METERING_API_ERROR	The metering API returned an error
METER_READING_GROUP_FAILED	A batch write of meter readings failed permanently after all retries — summary event alongside the per-reading errors
METER_READING_GROUP_RETRYING	A batch write of meter readings failed and will be retried automatically — one event per attempt covering the whole group (reading_count and external_ids in details)
MISSING_REQUIRED_PARAM	A required parameter is missing from the request
MISSING_UNIQUE_IDENTIFIERS	The event is missing the unique identifier field(s) required to match an entity
OAUTH2_TOKEN_FAILURE	Failed to obtain an OAuth2 access token
PAYLOAD_TOO_LARGE	The payload exceeded the maximum size accepted by the receiving system
PRUNE_SCOPE_PARTIAL_FAILURE	Scope pruning completed with some failures
RECURSION_DEPTH_EXCEEDED	Maximum recursion depth was exceeded during processing
RELATION_REF_ITEM_NOT_FOUND	The relation_ref target entity exists but the referenced item/value could not be matched — skipped as non-retryable. Check the mapping configuration and the entity data.
RELATION_REF_VALUE_UNDEFINED	A relation_ref mapping value resolved to undefined — check the mapping expression
REQUIRED_PARAM_MISSING	A param the use case marks as required resolved to nothing, so the delivery was stopped before anything was sent — see param_name
SECURE_PROXY_DISABLED	The secure proxy use case is disabled
SECURE_PROXY_DOMAIN_BLOCKED	The target domain is blocked
SECURE_PROXY_DOMAIN_NOT_ALLOWED	The target domain is not in the allowlist
SECURE_PROXY_ERROR	An error occurred in the secure proxy
SECURE_PROXY_INVALID_CONFIG	The secure proxy configuration is invalid
SECURE_PROXY_INVALID_TYPE	The secure proxy type is invalid
SECURE_PROXY_INVALID_URL	The target URL is invalid
SECURE_PROXY_IP_BLOCKED	The target IP address is blocked
SECURE_PROXY_IP_NOT_ALLOWED	The target IP address is not in the allowlist
SECURE_PROXY_NOT_FOUND	The secure proxy use case was not found
SECURE_PROXY_UNAVAILABLE	Secure proxy service is unavailable
SIGNATURE_VERIFICATION_FAILED	Request signature could not be verified
SIGNATURE_VERIFICATION_UNAVAILABLE	The file service could not be reached to verify the request signature
STEP_DISABLED	A request step's "run this step when" expression returned false, so this step and every step after it were skipped. This is the configuration working as written, not a fault.
TIMEOUT	The operation timed out
UNIQUE_ID_MULTIPLE_MATCHES	Multiple entities matched the unique ID
UNIQUE_ID_NOT_IN_SCHEMA	The unique ID attribute is not defined in the entity schema
UNKNOWN_ERROR	An unexpected error occurred during processing
USE_CASE_DISABLED	The use case is currently disabled
USE_CASE_INVALID_TYPE	The use case type is invalid or unsupported
USE_CASE_MISSING_CONFIG	The use case is missing required configuration
USE_CASE_NOT_FOUND	The use case could not be found

Warning

Processing continued, but something needs a human eye — often a retry in flight or a value nobody has mapped yet.

Code	What it means
ACK_TIMEOUT	Acknowledgement timed out waiting for the ERP system
EXTERNAL_WARNING	A warning span pushed by an external system via the external monitoring events endpoint.
FILE_PROXY_UPLOAD_RETRYING	A file upload failed with a retryable error and will be retried automatically — one event per attempt
LOOKUP_UNMAPPED	A value was not listed in a lookup table and its fallback was used — see lookup_name and lookup_key for the gap
SOFT_DELETED_ENTITY_MATCHED	A soft-deleted entity matched the unique ID — it will be resurrected on upsert, or referenced as-is by a relation. Investigate why the ERP source is sending events for a deleted entity.

Success

The event did what it was meant to do. Useful for confirming a sync actually landed.

Code	What it means
ENTITY_CREATED	A new entity was created in epilot
ENTITY_DELETED	An entity was deleted from epilot
ENTITY_NO_OP	No changes were needed for the entity
ENTITY_UPDATED	An existing entity was updated in epilot
EXTERNAL_SUCCESS	A success span pushed by an external system via the external monitoring events endpoint.
FILE_PROXY_OK	File proxy request completed successfully
FILE_PROXY_UPLOADED	The external system accepted the file
METER_READING_DELETED	One or more meter readings were deleted — emitted once per batch, not per reading (reading_count and external_ids in details)
METER_READING_UPSERTED	One or more meter readings were created or updated — emitted once per batch, not per reading (reading_count and external_ids in details)
PRUNE_SCOPE_COMPLETED	Scope pruning completed successfully
WEBHOOK_DELIVERED	Webhook was delivered successfully

Info

Lifecycle markers rather than outcomes: a message was queued, a duplicate was ignored, a step was skipped by configuration. Counted in total events, but excluded from the success rate.

Code	What it means
ACK_CONFIRMED	Acknowledgement was confirmed by the ERP system
ACK_PENDING	Acknowledgement is pending from the ERP system
DUPLICATE_EVENT	This event was already processed (duplicate)
EXTERNAL_INFO	An informational span pushed by an external system via the external monitoring events endpoint.
FAN_OUT_EMPTY	The split expression returned an empty list, so nothing was sent — expected for events that carry no relevant items
FILE_PROXY_UPLOAD_ENQUEUED	A per-file upload was accepted for delivery during fan-out
MSG_ACKED	Outbound message acknowledged by the polling consumer and removed from the queue
MSG_DEAD_LETTERED	Outbound message moved to the dead-letter queue after exhausting delivery attempts, or via an operator skip
MSG_ENQUEUED	Outbound message enqueued to the poll queue, awaiting consumption by the ERP
MSG_EXPIRED_UNPOLLED	Outbound message expired before being consumed — retention elapsed without a successful poll
MSG_HEAD_BLOCKED	Outbound stream halted by a poison head message (block policy) — requires operator unblock or consumer acknowledgement

Status-code families

Some codes are generated from an upstream response rather than drawn from the fixed list above.

Pattern	Level	What it means
HTTP_{status}	warning	The upstream system answered the proxied request with this HTTP status. The proxy itself worked — it reached the target and returned its answer — so the refusal is recorded against the use case that owns the request.