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.

Since these issues prevent the endpoint from being registered, an incoming request results in a 404 - Not Found response with this payload:

Recommended Approach: Use the Custom API status report 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?
    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?

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.

Incoming requests are processed and validated against the contract, which can result in the following errors:

Example

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.

Example

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?
Example

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?
Example

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.

Example

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 for details.

Example

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 for details.

Example

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.

Example

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.

  • 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.