Start integrating with ONEiO for free!

Basic Troubleshooting


Most errors can be identified by performing basic troubleshooting. Basic troubleshooting involves checking the endpoint status and the message feed for errors or warnings.

if you need further help to troubleshoot errors with your integration, please send an e-mail to


In this article, we will show you how to perform basic troubleshooting by identifying the main issue through the following steps:

  1. Check your endpoint status
  2. Check the message feed
  3. Inbound messages
  4. Routing messages
  5. Outbound messages
  6. More troubleshooting options


Check your endpoint status


The home view provides a list of your endpoints and their status. If the endpoint related to the current issue is active and has a status different from Operational, it should be investigated. It's also a quick way to determine when your endpoint has an inbound or outbound queue.

Inbound queues are mostly caused in cases where we receive a large number of messages at once. It can happen in the following scenarios:

  • In test environments when a large number of messages are created by mistake when the instance returns from a maintenance window and starts to send a lot of messages at once
  • When your endpoint is suspended but the instance still sends messages to this endpoint.
  • It can also happen when a poller endpoint type returns many messages at once. 

If you have an inbound queue caused by a large number of messages received at once, in most cases the queue will subside with time.


Suspended endpoints keep receiving inbound messages. Suspending an endpoint only stops sending outbound messages. If the suspended endpoint is a poller endpoint type, it will keep polling results unless the endpoint status and the entity status are set to 'suspended'.

Outbound queues
are mostly caused by a message 'stuck' in a recoverable error retry state (see more about recoverable errors here), or when we encounter problems/slowness sending messages to the destination instance. We send the messages to the destination instance as fast as we can, and as soon as we receive a response, we start to send the following message. If your instance is processing the messages slowly, it could lead to an outbound queue.

See more about ONEiO's UI Home view here


Check the message feed

Most errors can be identified by checking the message feed. In the message feed you have access to all successfully received incoming messages - pushed to us or pulled from ONEiO, matched rules, and all outbound messages (successfully sent or not). The message feed is the main tool for troubleshooting messages handled by ONEiO. 

When troubleshooting, there are three basic situations you should check by looking at the message feed:

  • Was the message received by ONEiO (Inbound messages)?
  • Was the message processed (Routing messages)?
  • Was the message sent to the integrated instance (Outbound messages)? 

Inbound messages

Was the message received by ONEiO?

If we successfully received the message and the message is not dropped by an inbound message filter (whitelist), you should see the message in the message feed. 


You can view the inbound message payload, and inbound lookups - message enrichment, non-inline attachments - by clicking on the message and clicking on 'see details' in the inbound column.


Message feed containing the inbound message attributes

The inbound message details show:

  1. Access to inbound data and all inbound additional calls (additional requests such as downloaded attachments, lookups, etc)
  2. Date / Time of which ONEiO received the inbound message
  3. Click to show in box 4: the inbound message payload, the raw inbound message payload,, the received headers, and the response provided by ONEiO


Message details containing the message's unprocessed payload and additional requests


The response provided by ONEiO to your instance containing the transaction ID. 

If you send a message to ONEiO and the message is not present in the message feed, the first action is to check if the message was successfully sent to ONEiO. 

REST / SOAP endpoints:

We always send a synchronous message back: If the message is successfully received and has no errors, we respond back with a transaction id. If the message is invalid, or the authentication is not successful, we respond back with an error message

If your message doesn't reach ONEiO, we always advise checking your instance for errors sent by ONEiO as a synchronous response: in most cases, it will contain the error reason.

There are several common reasons why a message may not reach ONEiO:

Issue Troubleshoot
Authentication/connection issues
Message issues
  • Check your instance for response errors: we always respond back.
    I.e. If your message body is sent in an invalid format, we respond with a synchronous error.
Endpoint issues
  • Your endpoint may be disabled. In this case, we respond back with a transaction id, and the received message is queued.
  • Your endpoint may contain an error. If your endpoint has an Error status, please contact our support team.

Poller endpoint type

Polling endpoints work differently from REST endpoints, as in this case, we will make a request to your instance instead of receiving a request from your instance. Pollers are currently not available as self-service endpoints. Our integration engineers work together with you to ensure the polling endpoint is working. Once the poller is set, it is rare to find problems, but they can occur.

Here are some reasons for your poller to stop receiving messages:

Issue Troubleshoot
Authentication issues
  • Check whether your endpoint has the correct authentication credentials to access your instance.
  • Ensure that your URI is reachable by ONEiO, especially if you are behind a firewall.
  • If you use certificates, please verify that the certificate is still valid.
Query /message issues
  • Check if the polling query has been changed or updated and if the response returns any results
  • Verify if the polling query is not returning an invalid payload or payloads with elements containing errors or invalid characters
  • Ensure that the polling query is using the correct date format.
  • Check if there are no new records since the last entity was returned
  • Verify if the polling query returns a valid payload (i.e. it returns a valid JSON or XML, and there are no invalid characters and similar document structure errors)
Endpoint issues
  • Your endpoint may be disabled. In this case, we respond back with a transaction id, and the received message is queued.
  • Your endpoint may contain an error. If your endpoint has an Error status, please contact our support team.

It is also important to verify the status of your poller. Note that polling should be enabled or suspended by entity, and enabling both system and entity pollers can result in an error. To avoid issues, it is recommended to keep the main poller status as suspended, and only enable or disable pollers on the entity level, as shown in the example below:


General Info - Polling status must be suspended


Entity types (entity) - Enable or disable your entity poller here.


Routing messages

Was the message processed?

If the inbound message matches a routing rule, it will be routed. If the message does not match a routing rule, the message will not be routed further.


1 - message matches a rule and is routed to the integrated instance. 2 - The message does not match a rule and is not routed to the integrated instance

Below you can find reasons for a message not being routed further or common message route errors:

Issue Troubleshoot
The message doesn't match a configured entity

The message entity could be blank or it contains an entity different from the one mapped on existing routing rules. 

The message does not match the routing rule attribute conditions
  • Check the inbound attribute conditions in the rule that supposedly should be triggered, and check the message payload: are the required attributes present? 
  • Check also if there is any typo/space in the inbound attributes.
  • Check if the rule's inbound attachment conditions are fulfilled.
The message does not match the routing rule operation
  • Create operations are valid for the first time the message id attribute is found in the conversation. The following messages are updates.
  • If the create operation fails (for instance, a misconfigured routing rule), the message reprocessing is allowed.
The message should have an attachment
  • Verify that the attachment is present in the message and that the rule's attachment mapping is selected.
  • Check if the rule's inbound attachment conditions are fulfilled.
  • Check the message details (See Details) if there is a failed attachment download attempt.
  • If your endpoint allows it, check the endpoint's attachment configuration and verify if your instance sends the attachment as configured.

If the message is routed by a routing rule but doesn't reach the outbound column:

Issue Troubleshoot
The message is routed, it doesn't reach the outbound column but there are no errors

Check if the rule's action is not 'process only' or 'drop the message'

The message is routed and seems to be delayed
  • Check if the message is not delayed by a delay attribute.
  • Sometimes there is an error in the message processing and the rule is waiting for an attribute to be set. 
  • This could happen when you set a delay condition for the rule, and it is waiting for a conversation variable to be set.
  • In a scenario where the previous operation has failed and the attribute was not set, the rule with a delay condition will be delayed and will not change its status.
  • In a common case: There is a failed CREATE message, and in the sequence, an UPDATE for this failed CREATE message. 
  • If the update rule has a Conversation delay attribute set, this message will be delayed forever, as the first CREATE failed and the conversation attribute was not set.

Outbound messages

Was the message sent to the integrated instance?

If the message was routed successfully, you should see the message in the outbound column

A green tooltip means that the message was successfully sent to your instance. If the message was successfully sent by ONEiO and it didn't reach your endpoint, verify your security layers and check if anything is blocking the message.

A message not sent successfully by ONEiO will show a tooltip other than green. The tooltip will show you the reason the message wasn't sent. Check the table below for a basic tooltip meaning:

Issue Troubleshoot
Blue tooltip (message delayed)

This means the message sending is delayed and this message is in the outbound queue. 

Usually, this happens when there is a slowness in sending messages to your instance, meaning your instance is processing the messages slowly. 

  • This error is related to your instance, so check your instance to fix what is causing the slowness.
    It also happens when there is an outbound queue caused by a recoverable error (see below). In this case, fixing the recoverable error or canceling the message will make the outbound queue flow again.
  • Your message also could be delayed if your Message Quota has been exceeded or if the subscription period has ended
Yellow tooltip (recoverable error)

A recoverable error means we are retrying to send a message due to an error. As this error is not in the unrecoverable error list, we will retry it indefinitely until receiving a successful response. 

  • Check the message's response for what is causing the error, so you can fix it, or cancel the message. 
Red tooltip (failed)

This means we failed to send the message to your instance, due to a failure before or after sending the message. All failed messages status contains the status added to your endpoint's unrecoverable error list, meaning we will not retry sending the message.

Failing before sending usually are related to an invalid outbound JSON. Check the outbound values, in special if you are using JSON_FRAGMENT attributes. 

  • Check the message outbound values, in special if you are using JSON_FRAGMENT attributes.
  • Check also if there is a need for replacing any special character who could cause the error (i.e. a line break).

Failing after sending means we received an error from your instance when we delivered the message.

Black tooltip (manually canceled) The message was manually canceled. You still can check the message details and access the outbound message payload, and if that is the case - outbound message retries.

When the message sending fails (failed after sending), you can check the tooltip and the message response for errors. 

In most cases, your instance will return details about what is happening and you will be able to fix the error. Basic errors are related to:

Issue Troubleshoot
Mandatory fields

Check if the outbound payload contains all mandatory fields your instance requires for the method used. 

A create method would require at least a title and description, and an update method requires the id. Your instance's documentation should provide you with more detail about each method and required fields.


Review your instance's ONEiO user and password. 

  • Check also if the correct authentication methods are configured. 
  • Does your instance requires OAuth configuration or it accepts a basic authentication?

Does your instance require any specific value to be sent in the message header? Check the message headers tabs and verify if the value is correct.

Correct methods/id

Check the message details for the used method (create, update, put, patch) and what it requires. 

If an update fails, does the method URI contain the entity ID? 

Check if the CREATE message was successful

Check the message conversation for errors. 

Usually, when a create message fails, all subsequent messages related to the source id also fail, as there is no message id (target id) for the following updates.

  • Does your instance's ONEiO user have enough grants for creating/updating messages? 
  • Does it have the right scope and access to the right projects?



You can view the outbound message payload by clicking on the message and clicking on 'see details' in the outbound column.


Message feed containing the outbound message attributes


The outbound message details show:

  1. All additional outbound requests, including lookups, attachment uploads, and recoverable error retries. If there is an error, you can see all retries. For example, if you encounter an HTTP error 401, it may not be configured as an unrecoverable error, and you can view all the retries. By clicking on each retry, you can view the retry date/time, payload, and error.
  2. Date / Time of which ONEiO sent the outbound message or the requested retry was performed
  3. URI the request was sent, method, and received HTTP status
  4. Click to show in box 5: the formatted message payload, the raw message, sent headers, or the Response received from the instance after sending the message.
  5. box containing the option selected above.


Example: After attempting to send a message, you should receive a response from the instance. In this case, the response indicates that the credentials are invalid.


Some systems reply with a successful HTTP status even if there are errors. In most cases, the response tab will bring you the error detail. 



Test basic methods with an external tool

Testing the requests externally is a good option, especially if it is a new integration and if you are performing tests in QA environment. Most of the providers have request/response examples by using CURL or Postman, and they are good tools for checking the basics:

  • Authentication
  • Get
  • Post
  • Put/Patch. 

Testing with an external tool is also useful to troubleshoot polling issues. Check if the poller query configured in your ONEiO endpoint returns the same data as the external request, and if it returns all required fields (i.e. last modified date, id)

Was this article helpful?
2 out of 2 found this helpful
Have more questions? Submit a request



Please sign in to leave a comment.