# Troubleshooting When a Custom API endpoint is not accessible as expected, this page can help to find the root cause. The following checklist is meant to verify the structure of the cartridge (for example, the folder structure), the required files and the request. However, it doesn’t include the implementation itself. ## Issues During Endpoint Registration Since these issues prevent the endpoint from being registered, an incoming request results in a **404 - Not Found** response with this payload: ```json { "title": "Resource Not Found", "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/resource-not-found", "detail": "Could not find requested resource" } ``` Recommended Approach: Use the [Custom API status report](/docs/commerce/b2c-commerce/guide/custom-api-status-report.md) to investigate endpoint registration issues. This status report provides detailed error information for endpoints that could not be registered, including specific error codes that help you quickly identify and resolve problems. If the Custom API status report doesn't provide sufficient information to resolve the issue, verify the following items manually: 1. Is the code version to which the Custom API components were uploaded the active code version? 2. Does the cartridge that includes the Custom API components have the correct structure? 1. Is the `rest-apis` folder included? 2. Does the `rest-apis` folder contain at least one subfolder? 3. Does the subfolder name of `rest-apis` consist of only alphanumeric lowercase characters or hyphens? 4. Does the subfolder of `rest-apis` contain the mapping file and at least one schema file and implementation script? 3. Is the cartridge that includes the Custom API components uploaded to the correct SFCC instance? 4. Is the cartridge that includes the Custom API components assigned to the correct site? 5. Is the version used in the request correct? 1. Is the corresponding API version defined in the schema file? 2. Does the API version match? API version and URL version have different formats (for example, API version `1.0.1` → URL version `v1`) 6. Is the schema file correct? 1. Is the structure of this file correct? 2. Is a version given? 3. Is the `securitySchemes` part given? 4. Is at least one endpoint given, including the attribute `operationId`? 5. Is the `security` field given, either globally or per endpoint? 6. Are `ShopperToken` or `AmOAuth2` used as a security scheme? 7. Does the corresponding security scheme define exactly one scope? 8. Does the scope name start with the prefix `c_` and consist of only alphanumeric characters, hyphens, periods or underscores? The custom scope name should also be 25 characters or less. 9. Are all parameters (system parameter and custom parameter) defined in the schema file? 10. Are the system parameters `siteId` and `locale` defined in the schema file? 1. Do the system parameters have a `schema` field with `type: string` and `minLength: 1`? 11. Do custom parameters start with the prefix `c_`? 12. Do all parameters have a defined type? 13. Does the definition of all parameters match the expected structure of parameter definitions? 7. Is the implementation script correct? 1. Are the respective endpoints exported in this implementation script? → see mapping file and schema file (attribute `operationId`) which endpoints should be exported by this script file. 2. Does the endpoint return a response in JSON format? 8. Is the mapping file correct? 1. Is the structure of this file correct? 2. Are no file extensions included in the name of the implementation scripts? 3. Are the schema files and implementation scripts in the same folder as the mapping file? 4. Does a schema file for this version exist? 5. Does an implementation script for this version exist? 6. Are the given endpoints referenced in the related schema file and the implementation script? 7. Does the value of the `endpoint` property match the function name in the script and the `operationId` in the schema? ### Investigate Registration Errors If the previous checklist does not help determine the error, review the log messages. Each registration failure creates a corresponding log message. 1. In Business Manager, navigate to **Administration** > **Site Development** > **Development Setup**. 2. In the *Log Files* section, click *Log Center*. 3. Select the Day of Year. 4. In the **LCQL** field, enter `CustomApiRegistry`. 5. The message text of the query hits should provide enough details to fix the issue in the correct file. ## Issues During Request Processing Incoming requests are processed and validated against the contract, which can result in the following errors: ### 400 - Bad Request - Example - : ```json { "title": "Bad Request", "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/undefined-query-parameter", "detail": "Found query parameter(s) not defined in the schema: 'c_type'" } ``` - Reason - : Errors of this type are typically caused by contract violations, for example: missing or unknown request parameters, or invalid parameter length. - Solution - : The response body should give a clear indication of the reason. ### 401 - Unauthorized - Example - : ```json { "title": "Unauthorized", "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unauthorized", "detail": "Invalid token provided." } ``` - Reason - : Errors of this type are caused by failed authentication, for example: missing or invalid authentication tokens. - Solution - : Verify the following items: 1. Does the request have an authentication token in the `Authorization` header? 2. Is the token (still) valid? ### 403 - Forbidden - Example - : ```json { "title": "Forbidden", "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/forbidden", "detail": "Request path is not allowed, because of missing or invalid permissions." } ``` - Reason - : Errors of this type are caused by failed authorization, typically a scope error. - Solution - : Verify the following items: 1. Is the token correctly configured with custom scopes? 2. Is one of the token scopes defined for the endpoint in the contract? ### 405 - Method Not Allowed - Example - : ```json { "title": "Method Not Allowed", "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/method-not-allowed", "detail": "The request method is not allowed for the requested resource" } ``` - Reason - : Errors of this type are returned if the endpoint path exists, but the request method is not defined in the contract. - Solution - : If this method is valid, add the corresponding operation to the contract. If it is not, change the request to use a different method. ### 406 - Not Acceptable - Example - : ```json { "title": "Unsupported Media Type", "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unsupported-media-type", "detail": "The media type 'application/xml' in the Accept header isn't supported.", "mediaType": "application/xml" } ``` - Reason - : Errors of this type are returned if the response media type defined in the contract is not acceptable by the client (for example: the endpoint always returns `application/json` but the client only accepts `application/xml` as defined in the `Accept` header.) - Solution - : If the requested media type is valid, add it to the corresponding operation in the contract. If it is not, change the request to use a supported media type, perhaps by using a wildcard. See the [specification](https://www.rfc-editor.org/rfc/rfc9110.html#name-accept) for details. ### 415 - Unsupported Media Type - Example - : ```json { "title": "Unsupported Content Type", "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/unsupported-content-type", "detail": "The media type 'application/xml' in the Content-Type header isn't supported. Note: Only the UTF-8 charset is supported.", "contentType": "application/xml" } ``` - Reason - : Errors of this type are returned if the media type of the request payload doesn't match the media type defined in the contract (for example: the payload is `application/xml` as indicated by the `Content-Type` header, but the endpoint expects `application/json`). - Solution - : If the supplied media type is valid, add it to the corresponding operation in the contract. If it is not, change the request to use a supported media type. See the [specification](https://www.rfc-editor.org/rfc/rfc9110.html#name-content-type) for details. *** ### 500 - Internal Server Error - Example - : ```json { "title": "Custom API Internal Server Error", "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/custom-api-internal-server-error" } ``` - Reason - : Errors of this type could indicate generic server errors during request processing. However, errors resulting from the implementation script will also return them with the type `custom-api-internal-server-error` like in the example above. - Solution - : Investigate the log messages to discover the reasons for these errors as described [here](/docs/commerce/b2c-commerce/guide/custom-api-circuit-breaker.md#investigate-script-errors). ### 503 - Service Unavailable - Example - : ```json { "title": "Custom API Circuit Breaker Error", "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/custom-api-circuit-breaker-error" } ``` - Reason - : Errors of this type indicate an open circuit breaker due to a high number of script errors. - Solution - : For more information on this protective mechanism and how to address these errors, see [Circuit Breaker](/docs/commerce/b2c-commerce/guide/custom-api-circuit-breaker.md). ## Issues with Remote Includes - SCAPI error responses: - If a 404 response code is received from the included resource, an empty JSON object '{}' is supplied in the final JSON. - For any other 4xx or 5xx response code that is received from the included resource, the final response status is 500 'Internal Server Error'. - Controller error responses: - The error response code is directly embedded into the resulting JSON. If your error responses are not valid JSON, the final response is invalid JSON.