Error Code Reference

Overview

The platform uses a single, stable error-coding scheme across all its API surfaces to provide consistent and predictable error handling. Every error code follows a standard format, which allows for precise identification of the issue's origin and nature.

All error codes conform to the structure S2R-<AREA>-<NNNN>:

• S2R: A static prefix identifying the product.
• <AREA>: A three-letter code indicating the subsystem that generated the error.
• <NNNN>: A stable, four-digit numeric code unique within its area. Retired codes are never reused.

These codes are surfaced on the Admin API (/admin/v1/*), the REST-to-SOAP runtime path (/publish/...), and the SOAP-to-REST runtime path (/consume/...).

Standard Error Envelope

Errors on the Admin API and the /publish runtime path are returned in a consistent JSON object.

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

The error object contains the following 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 or display.
details	Object	A code-specific object containing additional context. It may be empty ({}). For example, S2R-RUN-0413 includes maxPayloadMb, and runtime errors include the request path and environment.
correlationId	String	The unique ID for the request. Use this ID to trace the request through the platform's observability and logging systems.

Area Prefixes

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

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	Platform entitlement enforcement.
S2R-SYS-*	System	Unhandled/internal failures.

Error Code Reference by Area

This section provides a comprehensive list of all error codes, organized by their area prefix.

Validation Errors (S2R-VAL-*)

These errors relate to invalid input provided by an API consumer or invalid configuration.

Code	Meaning
S2R-VAL-0400	Invalid request body. Also used for runtime request mapping/contract validation errors; the failed JSON path is named in the message.
S2R-VAL-0401	Invalid field format.
S2R-VAL-0402	Unsupported enum value.
S2R-VAL-0403	Route definition conflict.
S2R-VAL-0405	OAuth2 client-credentials configuration is invalid (a required oauth2_* field is missing).
S2R-VAL-0406 · S2R-VAL-0407	Mapping-evidence request invalid or payload too large (2 MB per-row cap, HTTP 413).
S2R-VAL-0408 · S2R-VAL-0409	Traffic auto-suggest candidate mismatch or query parameters out of range.
S2R-VAL-0410	Runtime request failed OpenAPI v3 schema validation. Occurs only in enforce mode. See details.violations[] for per-field issues. Returns HTTP 400.
S2R-VAL-0411	Referenced OpenAPI import ID does not exist.
S2R-VAL-0415 · S2R-VAL-0435	Invalid request/response enforcement-mode value. Valid values are off / shadow / enforce or off / monitor / enforce. Returns HTTP 400.
S2R-VAL-0416	Cannot enable enforce mode on a SOAP Broker (GATEWAY) service with an incomplete or unresolved WSDL schema closure. Returns HTTP 409 on PATCH requests to enforcement-mode endpoints and on version :activate / :rollback actions if enforcement is already active. Remediation: Re-import the WSDL to resolve its xsd:import / wsdl:import dependencies, or fix the unresolved imports named in the error message, then retry. Alternatively, use monitor mode. This error is not raised for PUBLISH / CONSUME services.
S2R-VAL-0420 · S2R-VAL-0421	Invalid or expired test-execution JWT on the onboarding test surface. Returns HTTP 401.
S2R-VAL-0430	Backend response failed OpenAPI v3 schema validation, indicating upstream contract drift. Returns HTTP 502. See details.violations[] for details.
S2R-VAL-0436 · S2R-VAL-0437 · S2R-VAL-0438	Traffic-capture payload invalid, no captured samples found, or no OpenAPI artifact available for spec refinement.

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

These errors occur during administrative operations via the /admin/v1/* endpoints or during the admin-api service startup.

Code	Meaning
S2R-ADM-0403	Forbidden by role policy.
S2R-ADM-0404	Service, version, or operation not found.
S2R-ADM-0409	Duplicate key (service_key, operation_key, or path).
S2R-ADM-0410	Immutable-state conflict (HTTP 409). Examples: editing a non-draft/active version, creating a second draft, deleting an active service, or activating a BLOCKED draft.
S2R-ADM-0412 · S2R-ADM-0413	Mapping synthesis 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 validation round-trip. The admin-api will refuse to start.
S2R-ADM-0420	A backend profile has mtls_enabled=true, but the certificate/key PEM is missing or cannot be parsed.
S2R-ADM-0421	The pgcrypto database extension is missing. It must be installed by a database superuser.
S2R-ADM-0422	WSDL parse failed.
S2R-ADM-0424	WSDL declares an unsupported message format (use="encoded" for RPC/encoded SOAP). The 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, invalid scope, or an empty scopes array. To use the default full scope set, omit the scopes field entirely. Returns HTTP 400.
S2R-ADM-0430	Agent enrollment failed because an agent with the given agentId already exists. Returns HTTP 409.
S2R-ADM-0444	Agent enrollment succeeded, but the agent could not be read back from the database. Returns HTTP 500.
S2R-ADM-0500 · S2R-ADM-0503	Internal admin processing error or a required dependency (e.g., Cloud SQL, Storage, Parameter Manager) is 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. Returns HTTP 404.
S2R-RUN-0405	Bad URL. The /{direction}/ segment is missing or is not publish or consume. Returns HTTP 400. The response includes a suggestedPath.
S2R-RUN-0408	CONSUME: Unsupported inbound Content-Type, or the backend endpoint URL is blank/unparseable. Returns HTTP 400 or HTTP 502.
S2R-RUN-0409	CONSUME: Malformed inbound SOAP envelope. Returns HTTP 400 (soap:Client fault).
S2R-RUN-0410	CONSUME: The REST backend returned a 4xx client error. The upstream status and body are relayed in the details object. Returns HTTP 400 (soap:Client fault).
S2R-RUN-0411	CONSUME: Only HTTP POST method is accepted. Returns HTTP 405.
S2R-RUN-0413	Payload too large. The limit is 30 MB (maxPayloadMb=30). Returns HTTP 413.
S2R-RUN-0414	CONSUME: Failed to fetch an OAuth2 token for the backend request. Returns a SOAP 500 (soap:Server) fault.
S2R-RUN-0415	RPC/encoded SOAP response is not supported. The platform supports the document/literal wire format.
S2R-RUN-0419	Startup failed: The credential encryption key (S2R_CREDENTIAL_KEY) is not set. The runtime will refuse to start.
S2R-RUN-0420	mTLS is enabled, but the required certificate is missing or invalid.
S2R-RUN-0421	The stored WSDL for a CONSUME endpoint is malformed, preventing serve-back of the WSDL. Returns HTTP 500.
S2R-RUN-0424	Backend timeout after a single attempt. Returns HTTP 504.
S2R-RUN-0429	Backend retries exhausted for a PUBLISH request.
S2R-RUN-0502	The backend SOAP service returned a fault or server error. Returns HTTP 502.
S2R-RUN-0503	The backend profile is missing or inactive, or a connection/IO failure occurred. Returns HTTP 503.
S2R-RUN-0504	Failed to parse the SOAP response from the backend. Returns HTTP 502.
S2R-RUN-0505	CONSUME: Backend authentication configuration error. A required credential field was blank after decryption. The field name is provided in the error, but no sensitive values are exposed. Returns HTTP 502.
S2R-RUN-0506	Backend SOAP response contract drift. The response shape or type did not match the stored contract. For CONSUME, this can also indicate a failure to serialize the REST response into a SOAP envelope. The details object includes result_code=contract_drift and a path-aware driftReason. Returns HTTP 502.
S2R-RUN-0529	The circuit breaker is open, and the request to the backend was short-circuited. Returns HTTP 503 with the remaining open-window duration.

Worker Errors (S2R-WRK-*)

These errors originate from background worker processes, such as synthetic monitors or data retention jobs.

Code	Meaning
S2R-WRK-0419	The worker's CredentialsCipher.decrypt() function was called while the credential key was unset or blank. This is a per-call failure and is recorded on the affected synthetic-monitor row.
S2R-WRK-0420	A synthetic-monitor probe targeted a backend profile with mtls_enabled=true but found a missing or unparseable certificate.

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 with an HTTP 503 and a Retry-After header. Health and readiness probes are exempt and will continue to succeed.

System Errors (S2R-SYS-*)

These codes represent unexpected internal system failures.

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

HTTP Status Code Mapping

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 required route or entity was not found.
405	Method Not Allowed (e.g., CONSUME path accepts only POST).
409	A conflict with the current state of the resource (e.g., duplicate key, immutable state).
413	Payload too large.
422	Unprocessable Entity, typically due to parse or semantic mapping errors.
500 / 502 / 503 / 504	Server-side failures, including runtime, system, or backend issues.

See Also

• Logs & Tracing
• Offline Grace Period and Degraded Mode

---

All SOAP-to-REST docs