Loading…
Loading…
SOAP-2-REST by Specaria uses a single, stable error-code scheme across both API surfaces. Every code looks like:
SOAP-2-REST by Specaria uses a single, stable error-code scheme across both API surfaces. Every code looks like:
S2R-<AREA>-<NNNN>
S2R — product prefix.<AREA> — the subsystem that raised the error (see the table below).<NNNN> — a stable four-digit code. Codes are never re-used once retired.On the Admin API and the PUBLISH runtime path, errors are returned in one consistent JSON shape:
{
"error": {
"code": "S2R-RUN-0413",
"message": "Payload too large",
"details": {
"maxPayloadMb": 30
},
"correlationId": "00000000-0000-0000-0000-000000000000"
}
}
code — the stable S2R-* code.message — a human-readable summary, safe to log and surface.details — a code-specific object (may be empty {}). The exact keys depend on the code;
for example S2R-RUN-0413 carries maxPayloadMb, and runtime errors include the request
path and environment.correlationId — the request's correlation ID, the join key into every
observability surface.CONSUME exception. On the SOAP-facade (
/consume/...) runtime path, errors are returned as a SOAP Fault envelope (Content-Type: application/soap+xmlortext/xml) instead of this JSON shape, because SOAP clients require a fault response. The same error codes apply.
| 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. |
S2R-VAL-*)| Code | Meaning |
|---|---|
| S2R-VAL-0400 | Invalid request body (also the runtime request mapping/contract validation error; 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 config is invalid (a required oauth2_* field is missing). |
| S2R-VAL-0406 · S2R-VAL-0407 | Mapping-evidence request invalid / payload too large (2 MB per-row cap, HTTP 413). |
| S2R-VAL-0408 · S2R-VAL-0409 | Traffic auto-suggest candidate mismatch / query parameters out of range. |
| S2R-VAL-0410 | Runtime request failed OpenAPI v3 schema validation (only in enforce mode; details.violations[] per field). HTTP 400. |
| S2R-VAL-0411 | Referenced OpenAPI import id does not exist. |
| S2R-VAL-0415 · S2R-VAL-0435 | Invalid request/response enforcement-mode value (off / shadow / enforce; off / monitor / enforce). HTTP 400. |
| S2R-VAL-0420 · S2R-VAL-0421 | Invalid / expired test-execution JWT on the onboarding test surface. HTTP 401. |
| S2R-VAL-0430 | Backend response failed OpenAPI v3 schema validation (upstream contract drift; HTTP 502, details.violations[]). |
| S2R-VAL-0436 · S2R-VAL-0437 · S2R-VAL-0438 | Traffic-capture payload invalid / no captured samples / no OpenAPI artifact for spec refinement. |
S2R-VAL-04xxcodes in the0412–0414range relate to the DataPower connector's import-export surface (see connectors).
S2R-ADM-*)| Code | Meaning |
|---|---|
| S2R-ADM-0403 | Forbidden by role policy. |
| S2R-ADM-0404 | Service / version / operation not found. |
| S2R-ADM-0409 | Duplicate key (service_key / operation_key / path). |
| S2R-ADM-0410 | Immutable-state conflict (HTTP 409) — 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 — no WSDL-derived contract / no OpenAPI import available. |
| S2R-ADM-0419 | Startup preflight: the backend-credential encryption key (S2R_CREDENTIAL_KEY) is unset/blank or failed its round-trip. The admin-api refuses to start. |
| S2R-ADM-0420 | Backend profile has mtls_enabled=true but the certificate/key PEM is missing or unparseable. |
| S2R-ADM-0421 | The pgcrypto database extension is missing (must be installed by a DB superuser). |
| S2R-ADM-0422 | WSDL parse failed. |
| S2R-ADM-0424 | WSDL declares an unsupported message format (use="encoded" RPC/encoded SOAP); affected operations are listed. |
| S2R-ADM-0500 · S2R-ADM-0503 | Internal admin processing error / dependency unavailable (Cloud SQL, Storage, Parameter Manager). |
S2R-RUN-*)| Code | Meaning |
|---|---|
| S2R-RUN-0404 | Route not found. HTTP 404. |
| S2R-RUN-0405 | Bad URL — the /{direction}/ segment is missing or not publish/consume. HTTP 400; response carries suggestedPath. Shown as Bad-URL Attempts in Observability. |
| S2R-RUN-0408 | CONSUME — unsupported inbound Content-Type, or the backend endpoint URL is blank/unparseable. HTTP 400 / 502. |
| S2R-RUN-0409 | CONSUME — malformed inbound SOAP envelope. HTTP 400 (soap:Client fault). |
| S2R-RUN-0410 | CONSUME — REST backend returned a 4xx; upstream status/body relayed in details. HTTP 400 (soap:Client). |
| S2R-RUN-0411 | CONSUME — only HTTP POST is accepted. HTTP 405. |
| S2R-RUN-0413 | Payload too large (maxPayloadMb=30). HTTP 413. |
| S2R-RUN-0414 | CONSUME — OAuth2 token fetch failed. SOAP 500 (soap:Server). |
| S2R-RUN-0415 | RPC/encoded SOAP response not supported (document/literal is the supported wire format). |
| S2R-RUN-0419 | Startup: the credential encryption key (S2R_CREDENTIAL_KEY) is unset. The runtime refuses to start. |
| S2R-RUN-0420 | mTLS enabled but the certificate is missing/invalid. |
| S2R-RUN-0421 | Stored WSDL is malformed (CONSUME WSDL serve-back). HTTP 500. |
| S2R-RUN-0424 | Backend timeout (single attempt). HTTP 504. |
| S2R-RUN-0429 | Backend retries exhausted (PUBLISH retry loop). |
| S2R-RUN-0502 | SOAP backend fault / server error. HTTP 502. |
| S2R-RUN-0503 | Backend profile missing/inactive, or backend connect/IO failure. HTTP 503. |
| S2R-RUN-0504 | Backend SOAP response parse failure. HTTP 502. |
| S2R-RUN-0505 | CONSUME — backend auth configuration error (a required credential field is blank after decryption; the field name is named, no plaintext echoed). HTTP 502. |
| S2R-RUN-0506 | Backend SOAP response contract drift (response shape/type mismatch against the stored contract; result_code=contract_drift, path-aware driftReason). For CONSUME, also a REST-serialization / SOAP-envelope-build failure. HTTP 502. |
| S2R-RUN-0529 | Circuit breaker open — backend short-circuited. HTTP 503 with remaining open-window duration. |
Two runtime codes are retired and must not be reused:
S2R-RUN-0407(SOAP 1.2 rejection on CONSUME — both versions are now accepted) andS2R-RUN-0412(a client-certificate stub, superseded bymtls_enabled).
S2R-WRK-*)| Code | Meaning |
|---|---|
| S2R-WRK-0419 | Worker CredentialsCipher.decrypt() invoked with the credential key unset/blank. Per-call (not startup) failure; recorded on the affected synthetic-monitor row. |
| S2R-WRK-0420 | Synthetic-monitor probe hit a backend profile with mtls_enabled=true but a missing/unparseable certificate. |
S2R-LIC-*)| 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. HTTP 503 + Retry-After (PUBLISH JSON / CONSUME SOAP Fault). Health/readiness probes are never denied. See Offline grace & degraded mode. |
S2R-SYS-*)| Code | Meaning |
|---|---|
| S2R-SYS-0500 | Unhandled system exception. |
| S2R-SYS-0501 | Serialization / deserialization failure. |
| S2R-SYS-0502 | Cache / state sync failure. |
| HTTP | Meaning |
|---|---|
| 400 | Validation / input faults (and bad URL). |
| 401 / 403 | Authentication / authorization failures. |
| 404 | Missing route or entity. |
| 405 | Method not allowed (CONSUME accepts POST only). |
| 409 | Duplicate / immutable-state conflict. |
| 413 | Payload too large. |
| 422 | Parse or semantic mapping errors. |
| 500 / 502 / 503 / 504 | Runtime / system / backend failures. |