1. REST API Guide
  2. Configurable HTTP Status Codes in Inbound REST Responses

Configurable HTTP Status Codes in Inbound REST Responses

The Siebel REST Inbound framework can return standardized HTTP Status Codes and structured JSON error responses for data, service, workspace, and workflow REST services. The response format aligns with common REST API conventions and the Zalando Problem specification.

Use this feature to map a Siebel error identifier to the HTTP Status Code that best describes the condition returned to an API client. Customer mappings provide control over response status values without changing Oracle-delivered configuration. This feature is optional.

  • Standard HTTP Status Codes for REST responses.
  • Structured JSON error payloads.
  • Customer-controlled mapping of Siebel error identifiers to HTTP Status Codes.
  • Improved interoperability for REST clients and clearer OpenAPI documentation.

Standardized Error Response Format

When standardized error responses are enabled, REST Inbound services return a response in the following format:
{
  "type": "https://opensource.zalando.com/restful-api-guidelines/#status-code-503",
  "title": "Service Unavailable",
  "status": 503,
  "detail": "Database connection failed",
  "errorCode": "SBL-EAI-05001"
}

In the mapping file, these are the parameters and the ones you can customize.

Field Description Customer configurable
type URI reference that identifies the error category in the Zalando specification. Yes
title Short summary of the error. Yes
status HTTP status code returned in the response. Yes
detail Detailed error message. No
errorCode Original Siebel error identifier. No

Configure HTTP Status Code Mappings

Siebel uses proprietary error identifiers for different error conditions. Two JSON mapping files transform those identifiers into appropriate HTTP Status Codes.

Oracle-Delivered Mapping File

The siebel-error-map.json file is packaged in siebel.war for applicationcontainer_external. It contains Oracle-provided default mappings. Do not modify this file because upgrades can replace it.

Customer Mapping File

Create custom-error-map.json in the webapps folder of each applicationcontainer_external Tomcat instance. Use the same file content on every instance.

  • Add a customer mapping from a Siebel error identifier to an HTTP Status Code.
  • Override an Oracle-delivered mapping when a different HTTP Status Code is required.
  • Enable or disable standardized error responses.

Enable Standardized Error Responses

StandardizedErrorMessages is false by default, which preserves existing response behavior. To return responses in the standardized format, set the value to true in custom-error-map.json and restart applicationcontainer_external.
"StandardizedErrorMessages": {
  "StandardizedErrorMessages": true
}

Example Customer Mapping

The following example maps three Siebel error identifiers to HTTP Status Code 406 and supplies a customer title for each response. You give the title you wish to be associated with the Siebel error identifier to give the client more information on what to do about the error.

{
  "StandardizedErrorMessages": {
    "StandardizedErrorMessages": false
  },
  "SBL-EAI-04451": {
    "type": "https://opensource.zalando.com/restful-api-guidelines/#status-code-406",
    "title": "The value entered for the field value is too long...",
    "status": "406"
  },
  "SBL-DAT-00235": {
    "type": "https://opensource.zalando.com/restful-api-guidelines/#status-code-406",
    "title": "The value entered for the field value is too long",
    "status": "406"
  },
  "SBL-BPR-00162": {
    "type": "https://opensource.zalando.com/restful-api-guidelines/#status-code-406",
    "title": "Error invoking service EAI Siebel Adapter at method Upsert.",
    "status": "406"
  }
}

Mapping Precedence and Runtime Behavior

When both mapping files define the same Siebel error identifier, custom-error-map.json takes precedence. This lets customers change HTTP Status Codes without modifying Oracle-delivered content.

  • Mapping files load once during Application Interface or Tomcat startup and remain cached in memory.
  • Restart the AI node after changing either mapping file.
  • If no mapping exists, Siebel preserves the existing error message, generates the standardized JSON response when enabled, and applies a default HTTP Status Code where possible.
  • Some errors that occur before the error framework is invoked can continue to use the legacy response format.
  • One Siebel error identifier maps to one HTTP Status Code. Multiple identifiers can map to the same HTTP Status Code.

OpenAPI Documentation

This is the standardized error response schema in the Swagger or OpenAPI definition for REST services that use this feature.

components:
  schemas:
    ErrorModel:
      type: object
      required:
        - type
        - title
        - status
      properties:
        type:
          type: string
        title:
          type: string
        status:
          type: integer
        detail:
          type: string
        errorCode:
          type: string

Upgrade and Implementation Guidance

Follow these guidelines to maintain upgrade-safe, standards-aligned, and thoroughly tested custom error mappings.

  • Keep all customer mappings in custom-error-map.json.
  • Do not modify siebel-error-map.json; an upgrade can replace Oracle-delivered mappings.
  • Preserve custom-error-map.json during upgrades by making a backup before an update and restoring the custom mapping file afterwards.
  • Align HTTP Status Code mappings with enterprise API standards.
  • Update Swagger or OpenAPI definitions for affected public APIs.
  • Test negative scenarios after changing mappings.