Celigo provides powerful error-handling features to help you manage and remediate issues efficiently in your APIs. With automated error logging and detailed error messages, you can quickly diagnose and fix problems. You can configure error-handling rules to determine how failures are managed.
For example, errors can originate from connected applications or external systems that your API interacts with. A common issue is authentication failure, which can occur when API keys, OAuth tokens, or login credentials are incorrect or have expired.
Network connectivity problems, such as timeouts or service unavailability, can also prevent a successful connection to external platforms. Data mismatches between your API request and destination applications—such as unexpected field formats, missing required values, or API schema changes—can also cause failures.
Addressing errors often requires checking API credentials, verifying data formats, and consulting the external system’s documentation for recent updates or limitations.
Use Failed records () to choose whether the process should stop and return an error in the API response node if a record fails or continue to the next step. Based on the error code received at the Response picker, branching rules can be added, an error response can be configured and customized, and an error message can be sent to the user. When one of the lookups or imports encounters an error, you can:
-
Stop and return error via the API response node: This is the default. The API execution will stop for the record, and the errors array (including the error code, message, and source) will automatically be available in the API response branching node. Additionally, the “Success” boolean in the API response will be updated to
false
. -
Proceed to the next application regardless: The API execution will continue to the next step; however, the "errors" array needs to be manually mapped in results/response mapping to use that information in downstream steps.
When you create your API response, you can set a custom error message to prevent it from exposing internal error details. These custom errors are sent to the API consumer when they attempt to use the API and encounter an unexpected result.
Some errors, such as 400 (Bad Request)
, 401 (Unauthorized)
, 404 (Not Found)
, 413 (Payload Too Large)
, and 415(Unsupported Media Type)
, are returned to the API consumer even before the API starts running.
Once the API starts executing, any runtime errors will change the Success
boolean in your Response Picker to false
. The record will follow the error response path based on your Response Picker settings.
If you haven’t mapped the source record (which contains errors) to the response record, the Celigo platform will return internal error details in the response body, with a default status code of 500 (Internal Server Error)
.
To create a custom error message:
-
Open your error API response step and configure it using the available codes. Add your API's HTTP response body, including the error you want to display. You can't customize your error code, but Celigo provides an array of pre-existing codes that suit your needs.
-
Map your API response. Don't forget to include the error message in your mappings!
After mapping, you can preview the response in the API response node by clicking Preview. You can also test the error using test mode and see the results of a failed request in your request logs under → .
-
Optional: Test your error response using a third-party application.
To open your API's request log from the API builder list:
To open your API's request log from API builder:
After opening your request logs, you'll see a list of all requests on the left side. These requests can be sorted by timestamp, method, or response code. The Actions (...) menu allows you to delete a request log.
Log data is displayed on the right side and separated into API request, Pre-mapped response, and API response data tabs.
You can refresh the data to fetch the latest API requests by clicking Refresh . You will not see any request log entries without request history for the filtered criteria. Old request logs are purged based on your data retention policy (30, 60, 90, or 180 days).
All the data in your API logs can be copied using the Copy button.
This tab shows the API request's body, headers, and Other data (e.g., request URL, method, and requestSize). This is the API request as your API consumer sent it.
This tab lets you view the records before they're mapped in the API response. This includes the source records as they're sent, execution errors, and configuration errors.
Check the API request log execution errors to troubleshoot issues while keeping error details hidden from API consumers. Learn more about creating custom errors.
Configuration errors display if your API setup is incomplete—such as missing a Relative URI, HTTP method, status code in response nodes, or an unmerged branch. In these cases, you’ll see a 501 (Not Implemented)
error.
Execution error
Configuration error
The Celigo platform automatically returns errors when specific issues occur in the API request or on the server side so that API consumers understand why their API request has failed.
Scenario: When the error code will be returned |
Error code and description |
Response body sent to API consumer (can be viewed in API logs as well) |
Pre-mapped response in API request logs for API developer |
---|---|---|---|
The error code is sent in the following scenarios:
|
|
A single record is supported in the payload. The server will return an error automatically. |
N/A |
The API token is incorrect or not present in the API request header. |
|
N/A |
N/A |
The error code is sent in the following scenarios:
|
|
The requested URI - |
N/A |
If the API request size is greater than 5 MB |
|
API request cannot exceed 5 MB |
N/A |
If the media type is not JSON. NoteYou can use the Override request/response media type field in imports to use a different media type (e.g., XML or CSV). However, the final API response must be in JSON. |
|
Unexpected token <Token> is not valid JSON |
N/A |
The error code is sent in the following scenarios:
|
|
The record cannot be processed. Try again or contact the API publisher. |
|
If the number of requests made to an endpoint exceeds the global rate limit (1M/hour). |
|
Rate limit exceeded. Please try again after <X> seconds. |
N/A |
The error code is sent in the following scenarios:
|
|
|
Appropriate error source, code and message will be available under Execution errors in the Pre-mapped response tab of your error logs. |
The error code is sent in the following scenarios:
|
|
An error occurred while processing the request. Contact the API publisher and try again later. |
|
If the API execution takes longer than the configured timeout period. |
|
API execution took longer than expected. Please try again. |
Timeout error occurred at <stepName> step. |
Reviewing the error messages and codes provided during the test run is extremely important. These messages often contain specific details about what went wrong and where. By thoroughly analyzing test run errors, you can proactively resolve issues, optimize your API, and ensure it works as expected before deployment.
You can perform debugging for every step of your API, including the request and responses, branches, lookups, and imports. Look for the blue T that designates a test run log as available for that step.
To view your test run errors:
-
Use the Test run
button to run a test.
-
After completing your test, review the Run console to see where your errors occurred.
-
Click the error button or the blue T in the step to open the Test run errors window. In steps where only the blue T appears instead of the error indicator, you'll need to open the step first; then, use the View debug logs button to open the logs for the step.
-
Review your errors.