Error handling in API builder covers two concerns. The first is diagnosing errors 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 using the response picker, custom error responses, and response mapping to shape what consumers receive.
Diagnose errors in your API
To review a request's execution details — response code, duration, payloads, and a step-by-step trace of what happened — use request history. See View API request and execution logs in API builder.
To investigate errors from a test run before you deploy, see Test and debug your API using API builder.
Control what your API consumers see
Use Failed records () to choose whether your API should stop and return an error in the API response node when a record fails, or continue to the next step. Based on the error code received at the Response picker, you can add branching rules, configure and customize an error response, and send an error message to the user. When a lookup or import encounters an error, you can:
-
Stop and return error via the API response node (the default) — API execution stops for that record, and the errors array, including the error code, message, and source, becomes available in the API response branching node automatically. The Success boolean in the API response updates to
false. -
Proceed to the next application regardless — API execution continues to the next step, but you need to map the
errorsarray manually in results or response mapping to use that information downstream.
When you configure your API response, you can set a custom error message so the response doesn't expose internal error details. API consumers see these custom errors when they encounter an unexpected result.
Some errors — 400 (Bad Request), 401 (Unauthorized), 404 (Not Found), 413 (Payload Too Large), and 415(Unsupported Media Type) — are returned to the consumer before the API even starts running.
Once the API starts executing, a runtime error changes the Success boolean in your Response Picker to false, and the record follows the error response path your Response Picker settings define. If you haven't mapped the source record — which contains the error — to the response record, the response body includes internal error details by default, with a 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, select Preview in the API response node to see the response. If you can view request logs, you can also test the error using test mode and see the results of a failed request under Request history → Open trace view in your request logs.
-
Optional: Test your error response using a third-party application.
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 (Request log access required) |
|---|---|---|---|
|
The error code is sent in the following scenarios:
|
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:
|
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. 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. |
415 - Unsupported media type |
Unexpected token <Token> is not valid JSON | N/A |
|
The error code is sent in the following scenarios:
|
422 - Unprocessable Content |
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). |
429 - Too many requests |
Rate limit exceeded. Please try again after <X> seconds. | N/A |
|
The error code is sent in the following scenarios:
|
500 - Internal Server Error |
|
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:
|
501 - Not implemented |
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. |
504 - API timeout |
API execution took longer than expected. Please try again. | Timeout error occurred at <stepName> step. |