Building an API in API builder takes more than configuring requests, responses, and steps. You also need a way to confirm it works correctly and to understand what happened when it doesn't. API builder gives you three tools for that: test mode, for validating your configuration before you deploy; request history and trace view, for reviewing what happened after a request runs; and error handling controls, for shaping what your API consumers see when something fails. Two API settings also change how the API responds: one for offline connections and one for requests and responses that don't match your schemas.
Use the article that matches what you're trying to do:
- Before you deploy your API: Run your API in test mode against mock data and review how each step behaves, without affecting live records. See Test and debug your API using API builder.
- After your API is live: Review inbound requests in request history, turn on debug logging for more detail, and open trace view to follow a specific request step by step. See View API request and execution logs in API builder.
- When consumers see an error: Configure your response picker, custom error responses, and response mapping so consumers receive clear, appropriate errors instead of internal details. See Error handling in API builder.
- When a connection your API uses is offline: Find out why requests fail with HTTP 500 or 504 and how to resolve them. See Troubleshoot offline connection failures.
- When validation rejects a request or response: Find out why callers get HTTP 400, 500, or 501 when Enable request/response validation is on. See Troubleshoot schema validation failures.
Troubleshoot offline connection failures
When a connection your API uses is offline, the API fails in one of two ways, depending on the API's Immediate error for offline connections setting. To change the setting, see Set how an API handles offline connections. To find these failures in request history, see Find offline connection failures.
Your API returns HTTP 500 immediately
Cause: The setting is on, and a connection the API uses is offline.
Resolution: Open Connections in API builder to find the offline connection, then fix the offline connection. Callers can retry once the connection is back online. The caller receives the message "One or more connections used by this API are offline. Contact the API publisher and try again later."
Requests wait, then fail when the API times out
Cause: The setting is off, and the request reached a step whose connection is offline. The request waited until the API's timeout ran out: the Override timeout value, or the Organization-wide API timeout limit if no override is set.
Resolution: Fix the offline connection. If callers can't wait, turn the setting on.
Troubleshoot schema validation failures
When Enable request/response validation is on, API builder rejects requests and responses that don't match your schemas. To learn how validation works, see Validate API requests and responses in API builder.
Your API returns HTTP 400 with a message about a field or query parameter
The caller sees one of these messages:
- Query parameter <paramName> is required and must not be empty.
- <paramName> is required and must not be empty.
- <paramName> must be <data type, e.g. string, number>.
- <paramName> must be one of: <enum values>.
- <paramName> must match <pattern, such as
^[A-Za-z0-9]+$>. - <paramName> must be at least <min length> characters.
- <paramName> must be at most <max length> characters.
- <paramName> must be at least <min quantity>.
- <paramName> must be at most <max quantity>.
Cause: The request doesn't meet a rule in the API request. The message names the field or query parameter and the rule it broke. A query parameter marked Required also fails when it's empty or contains only spaces.
Resolution: Compare the request with the rules in the API request, in Visual or JSON. Change the request so it meets the rule, or change the rule if it's too strict. To check a mock request against the saved schema, select Preview on the API request.
Your API returns HTTP 500 and a message that the response didn't match its schema
The caller sees this message: The API response didn't match its schema. Contact the API owner.
Cause: The response body doesn't match the schema of the response node that ran.
Resolution: Run a test. The error indicator on the response node shows which field fails. Fix the mapping or the response schema, and then test again. If a step already ran before the failure, check whether the caller's retry repeats a write, because earlier steps aren't undone.
Your API returns HTTP 501 because API builder can't check a schema
Cause: A saved schema has a rule that API builder can't run. Some regular expressions save but can't be run.
Resolution: Run a test. The test returns HTTP 501 and names the schema location. Correct the rule in that field, and then save.