Error handling in API builder

Kathyana Queeman

Updated May 20, 2025 16:28

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.

Error handling for failed records

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.

Create custom error handling

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 Pre-mapped response → Execution errors.
Optional: Test your error response using a third-party application.

Open and view your request logs

To open your API's request log from the API builder list:

Click Resources → APIs.
Navigate to the API builder tab.
Find your API in the list and click Actions (...) → View request logs.

To open your API's request log from API builder:

Click Resources → APIs → API builder → <Your API>.
Click Actions overflow (...) → View request logs.

Navigate your request logs

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.

API request

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.

Pre-mapped response

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

API response

This is the API response sent to your API consumer. This tab shows the API response's body, headers, and Other data (e.g., statusCode, responseSize, and duration).

Common error codes

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: The payload JSON format is incorrect Special characters in invoke URL Payload is not a plain object Request URI length exceeds the limit	`400` - Bad request	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.	`401` - Unauthorized	N/A	N/A
The error code is sent in the following scenarios: If the request URL doesn’t match any of the endpoint URLs in the scope of the API token If the API is disabled	`404` - Not found	The requested URI - `{{method}} {{originalUrl}}` could not be found.	N/A
If the API request size is greater than 5 MB	`413` - Payload too large	API request cannot exceed 5 MB	N/A
If the media type is not JSON. Note You 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.	`415` - Unsupported media type	Unexpected token <Token> is not valid JSON	N/A
The error code is sent in the following scenarios: Special characters in invoke URL If the output from a lookup exceeds 5MB Unexpected processing error in any of the steps in API builder (e.g., response node, pre-map, mapping, post-map).	`422` - Unprocessable Content	The record cannot be processed. Try again or contact the API publisher.	Special characters in invoke URL Output from a lookup exceeds 5MB Unexpected processing error at [stepName] step: <errorDetails>
If the number of requests made to an endpoint exceeds the global rate limit (1M/hour).	`429` - Too many requests	Rate limit exceeded. Please try again after <X> seconds.	N/A
The error code is sent in the following scenarios: Celigo integrator.io services are down Response size exceeds 5 MB If the connection is offline for any of the endpoints If any of the endpoints return a Concurrency error	`500` - Internal Server Error	NA Response stream exceeded limit of <X> bytes Connection is taken offline: missing <>	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: API request node not configured (Relative URI, HTTP method) API response nodes are not configured (status code not defined) or mapped Import/lookup is not configured Dangling branch	`501` - Not implemented	An error occurred while processing the request. Contact the API publisher and try again later.	API request node not configured API response node not configured <stepName> not configured One or more branches are not merged back. Review the setup to ensure all branches converge.
If the API execution takes longer than the configured timeout period.	`504` - API timeout	API execution took longer than expected. Please try again.	Timeout error occurred at <stepName> step.

Review test run results and errors

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.

View your test run error logs

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.