Error handling in API builder

Kathyana Queeman

Updated July 22, 2026 19:52

Error handling in API builder covers two concerns. The first is diagnosing errors that occur during API execution — understanding what went wrong, where it happened, and how to fix it. The second is controlling what your API consumers see when something fails — returning clear, appropriate error responses instead of exposing internal details.

This article covers both. Use request history and test run logs to investigate execution errors. Use the response picker, custom error responses, and response mapping to shape what consumers receive.

Diagnose errors in your API

Open and view your request logs

Request logs are only available for legacy sandbox environments. Learn more about multiple environments. 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).

To investigate errors during a test run before deployment, see Test and debug your API using API builder.

Control what your API consumers see

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.

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.