SOAP-2-REST API Error Codes

Overview

The SOAP-2-REST platform uses a single, stable error-coding scheme across all its API surfaces to provide consistent and actionable error information. This document provides a canonical reference for all error codes, their meanings, and the structure in which they are delivered.

All errors are identified by a unique code that indicates the product, the subsystem that generated the error, and a specific error number. This system allows API consumers and operators to reliably identify and handle failure conditions.

Error Code Structure

Every error code follows a consistent format: S2R-<AREA>-<NNNN>.

• S2R: A static prefix identifying the SOAP-2-REST product.
• <AREA>: A three-letter code for the subsystem that raised the error. See the Area Prefixes table for a list of subsystems.
• <NNNN>: A stable, four-digit numeric code unique within its area. Once a code is retired, it is never reused.

The Standard Error Envelope

On the Admin API (/admin/v1/*) and the PUBLISH runtime path (/publish/...), errors are returned in a standard JSON object.

Example Error Response

{
  "error": {
    "code": "S2R-RUN-0413",
    "message": "Payload too large",
    "details": {
      "maxPayloadMb": 30
    },
    "correlationId": "00000000-0000-0000-0000-000000000000"
  }
}

Envelope Fields

Field	Type	Description
code	String	The stable S2R-* error code.
message	String	A human-readable summary of the error. This message is safe to log and surface in user interfaces.
details	Object	A code-specific object containing additional context. This may be an empty object ({}). For example, S2R-RUN-0413 includes maxPayloadMb, and runtime errors include the request path and environment.
correlationId	String	The unique ID for the request. This ID is the primary key for correlating a request across all platform observability surfaces, such as logs and traces.

SOAP Fault Exception

For requests to the CONSUME runtime path (/consume/...), errors are returned as a SOAP Fault envelope with a Content-Type of application/soap+xml or text/xml. This is to ensure compatibility with SOAP clients that expect a fault response. The same S2R-* error codes are used within the SOAP Fault.

Area Prefixes

The <AREA> component of the error code identifies the subsystem where the error originated.

Prefix	Subsystem	Where it surfaces
S2R-VAL-*	Validation / input	Admin API request validation; runtime request/response schema validation.
S2R-ADM-*	Admin / control-plane	/admin/v1/* operations and admin-api startup preflight.
S2R-RUN-*	Runtime / data-plane	/publish/... and /consume/... conversion traffic.
S2R-WRK-*	Background worker	Scheduled jobs (synthetic monitor, retention sweeps).
S2R-LIC-*	Licensing	Specaria-platform entitlement enforcement.
S2R-SYS-*	System	Unhandled/internal failures.

Validation Errors (S2R-VAL-*)

These errors relate to invalid input, either in Admin API requests or during runtime request/response schema validation.

Code	Meaning
S2R-VAL-0400	Invalid request body. Also used for runtime request mapping/contract validation errors; the failed JSON path is specified in the message.
S2R-VAL-0401	Invalid field format.
S2R-VAL-0402	Unsupported enum value.
S2R-VAL-0403	Route definition conflict.
S2R-VAL-0405	The OAuth2 client-credentials configuration is invalid; a required oauth2_* field is missing.
S2R-VAL-0406 · S2R-VAL-0407	Mapping-evidence request is invalid or its payload is too large. A per-row cap of 2 MB applies. Responds with HTTP 413.
S2R-VAL-0408 · S2R-VAL-0409	Traffic auto-suggest candidate mismatch or query parameters are out of range.
S2R-VAL-0410	Runtime request failed OpenAPI v3 schema validation. This occurs only when the enforcement mode is enforce. The details.violations[] array lists each violation. Responds with HTTP 400.
S2R-VAL-0411	The referenced OpenAPI import ID does not exist.
S2R-VAL-0415 · S2R-VAL-0435	Invalid value for request/response enforcement mode. Valid values are off / shadow / enforce or off / monitor / enforce. Responds with HTTP 400.
S2R-VAL-0420 · S2R-VAL-0421	The test-execution JWT provided on the onboarding test surface is invalid or expired. Responds with HTTP 401.
S2R-VAL-0430	The backend response failed OpenAPI v3 schema validation, indicating upstream contract drift. The details.violations[] array lists each violation. Responds with HTTP 502.
S2R-VAL-0436 · S2R-VAL-0437 · S2R-VAL-0438	Traffic-capture payload is invalid, contains no captured samples, or there is no OpenAPI artifact for spec refinement.

Note: Error codes in the range S2R-VAL-0412 to S2R-VAL-0414 are related to the DataPower connector's import-export surface.

Admin / Control-Plane Errors (S2R-ADM-*)

These errors occur during operations on the Admin API (/admin/v1/*) or during the Admin API's startup sequence.

Code	Meaning
S2R-ADM-0403	Forbidden by role policy.
S2R-ADM-0404	The requested service, version, or operation was not found.
S2R-ADM-0409	A resource with the specified service_key, operation_key, or path already exists.
S2R-ADM-0410	An immutable-state conflict occurred (HTTP 409). This can be triggered by attempting to edit a non-draft/active version, create a second draft for a service, delete an active service, or activate a BLOCKED draft.
S2R-ADM-0412 · S2R-ADM-0413	Mapping synthesis is blocked because no WSDL-derived contract or OpenAPI import is available.
S2R-ADM-0419	Startup preflight check failed: The backend-credential encryption key (S2R_CREDENTIAL_KEY) is not set, is blank, or failed a round-trip encryption/decryption test. The Admin API will refuse to start.
S2R-ADM-0420	A backend profile has mtls_enabled=true, but the required certificate/key PEM data is missing or cannot be parsed.
S2R-ADM-0421	The pgcrypto database extension is missing. This extension must be installed by a database superuser.
S2R-ADM-0422	Failed to parse the provided WSDL.
S2R-ADM-0424	The WSDL declares an unsupported message format (use="encoded" for RPC/encoded SOAP). Affected operations are listed in the error details.
S2R-ADM-0426 · S2R-ADM-0428 · S2R-ADM-0429	Agent enrollment (POST /admin/v1/agents) failed due to an invalid agentId, an invalid scope, or an empty scopes array. To use the default full scope set, omit the scopes field entirely. Responds with HTTP 400.
S2R-ADM-0430	Agent enrollment failed because an agent with the given agentId already exists. Responds with HTTP 409.
S2R-ADM-0444	Agent enrollment succeeded, but the agent resource could not be read back from the database. Responds with HTTP 500.
S2R-ADM-0500 · S2R-ADM-0503	An internal processing error occurred in the admin service, or a required dependency (e.g., Cloud SQL, Storage, Parameter Manager) was unavailable.

Runtime / Data-Plane Errors (S2R-RUN-*)

These errors occur during live traffic processing on the /publish/... and /consume/... paths.

Code	Meaning
S2R-RUN-0404	Route not found. Responds with HTTP 404.
S2R-RUN-0405	Bad URL. The /{direction}/ segment is missing or is not publish or consume. The response includes a suggestedPath. Responds with HTTP 400. This is tracked as Bad-URL Attempts in observability dashboards.
S2R-RUN-0408	CONSUME only: The inbound Content-Type is unsupported, or the backend endpoint URL is blank or unparseable. Responds with HTTP 400 or 502.
S2R-RUN-0409	CONSUME only: The inbound SOAP envelope is malformed. Responds with HTTP 400 and a soap:Client fault.
S2R-RUN-0410	CONSUME only: The backend REST service returned a 4xx client error. The upstream status and body are relayed in the details object. Responds with HTTP 400 and a soap:Client fault.
S2R-RUN-0411	CONSUME only: The request used a method other than HTTP POST, which is the only accepted method. Responds with HTTP 405.
S2R-RUN-0413	The request payload is too large. The default limit is 30 MB (maxPayloadMb=30). Responds with HTTP 413.
S2R-RUN-0414	CONSUME only: The platform failed to fetch an OAuth2 token for the backend service. Responds with a SOAP 500 (soap:Server) fault.
S2R-RUN-0415	The backend returned an RPC/encoded SOAP response, which is not supported. The platform supports the document/literal wire format.
S2R-RUN-0419	Startup check failed: The credential encryption key (S2R_CREDENTIAL_KEY) is not set. The runtime will refuse to start.
S2R-RUN-0420	mTLS is enabled for the backend, but the required client certificate is missing or invalid.
S2R-RUN-0421	The stored WSDL for a CONSUME endpoint is malformed and cannot be served back. Responds with HTTP 500.
S2R-RUN-0424	The request to the backend timed out (based on a single attempt). Responds with HTTP 504.
S2R-RUN-0429	All configured backend retries have been exhausted (applies to the PUBLISH retry loop).
S2R-RUN-0502	The backend SOAP service returned a fault or a server error. Responds with HTTP 502.
S2R-RUN-0503	The backend profile is missing or inactive, or a connection/IO failure occurred when communicating with the backend. Responds with HTTP 503.
S2R-RUN-0504	The platform failed to parse the SOAP response from the backend. Responds with HTTP 502.
S2R-RUN-0505	CONSUME only: Backend authentication is misconfigured. A required credential field was blank after decryption. The field name is identified in the error, but no sensitive values are exposed. Responds with HTTP 502.
S2R-RUN-0506	Backend SOAP response indicates contract drift. The response shape or types do not match the stored contract. The details object contains result_code=contract_drift and a path-aware driftReason. For CONSUME, this can also indicate a failure to serialize the REST response into a SOAP envelope. Responds with HTTP 502.
S2R-RUN-0529	The circuit breaker for the backend is open. The request was short-circuited without being sent to the backend. Responds with HTTP 503 and includes the remaining duration of the open-window.

Note on Retired Codes: The codes S2R-RUN-0407 and S2R-RUN-0412 are retired and no longer in use. S2R-RUN-0407 was for SOAP 1.2 rejection on CONSUME endpoints (both versions are now accepted). S2R-RUN-0412 was superseded by the mtls_enabled configuration.

Worker Errors (S2R-WRK-*)

These errors are generated by background worker processes, such as the synthetic monitor.

Code	Meaning
S2R-WRK-0419	The worker's CredentialsCipher.decrypt() method was invoked, but the credential encryption key was unset or blank. This is a per-call failure, not a startup failure, and is recorded on the affected synthetic-monitor row.
S2R-WRK-0420	A synthetic-monitor probe attempted to contact a backend profile with mtls_enabled=true but the configured certificate was missing or unparseable.

Licensing Errors (S2R-LIC-*)

These errors relate to platform entitlement and licensing enforcement.

Code	Meaning
S2R-LIC-0030	The Specaria upstream platform has been unreachable beyond the configured hard-stop window (default 30 days). The runtime denies traffic to enforce licensing. The response includes an HTTP 503 status and a Retry-After header. Health and readiness probes are exempt and will not be denied.

System Errors (S2R-SYS-*)

These codes are for unhandled or internal system failures.

Code	Meaning
S2R-SYS-0500	Unhandled system exception.
S2R-SYS-0501	Serialization / deserialization failure.
S2R-SYS-0502	Cache / state sync failure.

HTTP Status Code Summary

The platform uses standard HTTP status codes to indicate the class of an error.

HTTP Status	General Meaning
400	Validation or input faults, including bad URLs.
401 / 403	Authentication or authorization failures.
404	A requested route or entity was not found.
405	Method Not Allowed (e.g., non-POST to CONSUME).
409	A conflict with the current state of a resource (e.g., duplicate key, immutable state).
413	Payload too large.
422	Unprocessable Entity due to parse or semantic mapping errors.
500 / 502 / 503 / 504	Runtime, system, or backend failures.

See Also

• Observability: Logs & Tracing
• Licensing: Offline Grace & Degraded Mode

---

All SOAP-to-REST docs