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 shows how to use the response picker, custom error responses, and response mapping to shape the errors consumers receive, and lists the error codes the Celigo platform returns.
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 are returned to the consumer before the API starts running: 400 (Bad Request), 401 (Unauthorized), 404 (Not Found), 413 (Payload Too Large), and 415 (Unsupported Media Type).
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. 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 (developer view; 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. | 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 (about 1,080,000 requests per 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 the API uses is offline and Immediate error for offline connections is on; or an endpoint returns a concurrency error | 500 - Internal Server Error | N/A; or "Response stream exceeded limit of <X> bytes"; or "One or more connections used by this API are offline. Contact the API publisher and try again later." | 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 its timeout (Override timeout, or the Organization-wide API timeout limit if no override is set). This includes a request that waits for an offline connection when Immediate error for offline connections is off. | 504 - API timeout | API execution took longer than expected. Please try again. | Timeout error occurred at <stepName> step. |
Note: To return a media type other than JSON from an import or lookup (such as XML or CSV), use the Override request/response media type field in that step. The final API response must be in JSON.
Whether an offline connection returns 500 or 504 depends on the API's Immediate error for offline connections setting. See Create and manage APIs using API builder.