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 is returned | Error code and description | Response body sent to the API consumer (also viewable in API logs) | Pre-mapped response in API request logs for the API developer (Request log access required) |
|---|---|---|---|
| The payload JSON format is incorrect; special characters appear in the invoke URL; the payload isn't a plain object; or the 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 missing from the API request header | 401 - Unauthorized | N/A | N/A |
| The request URL doesn't match any endpoint URL in scope of the API token, or the API is disabled | 404 - Not found | The requested URI - {{method}} {{originalUrl}} could not be found. | N/A |
| The API request size is greater than 5 MB | 413 - Payload too large | API request cannot exceed 5 MB | N/A |
|
The media type isn't JSON.
> Note: Use the Override request/response media type field in imports to use a different media type (such as XML or CSV) — but the final API response must be in JSON. |
415 - Unsupported media type | Unexpected token <Token> is not valid JSON | N/A |
| Special characters appear in the invoke URL; a lookup's output exceeds 5 MB; or an unexpected processing error occurs in any step (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 5 MB; or unexpected processing error at [stepName] step: <errorDetails> |
| Requests to an endpoint exceed the global rate limit (1M/hour) | 429 - Too many requests | Rate limit exceeded. Please try again after <X> seconds. | N/A |
| Celigo's integrator.io services are down; response size exceeds 5 MB; a connection is offline for any endpoint; or an endpoint returns a concurrency error | 500 - Internal Server Error | N/A; or "Response stream exceeded limit of <X> bytes"; or "Connection is taken offline: missing <>" | Appropriate error source, code, and message are available under Execution errors in the Pre-mapped response tab of your error logs. |
| The API request node isn't configured (relative URI, HTTP method); API response nodes aren't configured or mapped (status code not defined); an import or lookup isn't configured; or a branch is dangling | 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; or one or more branches aren't merged back — review the setup to ensure all branches converge. |
| 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. |