RPC error codes
RpcErrorDetail includes:
| Field | Meaning |
|---|---|
message | Human-readable explanation. |
stack | Stack trace when available (often null on validation errors). |
layer | 'validation', 'expected', or 'unexpected'. |
code | Machine-readable string; mirrors the response label when not overridden. |
On error responses, RpcResponse.status is 'error', result is null, returnType is 'error', returnShape is null, and label identifies the failure class.
Common code / label values
| Code / label | When |
|---|---|
INVALID_FN_KEY | fnKey missing . separator. |
FN_NOT_FOUND | Key not present in registry (message lists available keys). |
WRONG_ARG_COUNT | args.length ≠ declared params length. |
INPUT_SCHEMA_INVALID | Params JSON Schema validation failed (layer: validation). |
RETURN_SCHEMA_INVALID | Return JSON Schema validation failed after invoke. |
HTTP_BRIDGE_NOT_CONFIGURED | invokeKind is http_synthetic but no bridge spec exists. |
NOT_A_FUNCTION | Callable missing on class or function entry. |
NO_INSTANCE | Class entry without resolvable instance / method. |
INVOKE_TIMEOUT | Handler exceeded configured timeout. |
RESULT_NOT_SERIALIZABLE | Serialization rejected the result value. |
RATE_LIMITED | Token bucket rejected invoke (transports). |
UPLOAD_MATERIALIZE_FAILED | File placeholder could not be resolved to bytes (transports). |
UNEXPECTED_ERROR | Uncaught exception path (often layer: unexpected). |
Socket.IO transport (attachCatRPC)
These come from attachCatRPC (sdk/ts/src/transport/socket-io-playground.ts), not from executeRPC alone.
| Code / label | When |
|---|---|
UNAUTHENTICATED | secretApiKey is set on attachCatRPC and isDevelopment is false (production). A registerPreInvoke hook rejects every rpc:call before invoke. Message: Pipeline is cannot be invoked in production mode. error.layer is validation. Use isDevelopment: true (or omit secretApiKey in prod) if the QA pipeline must invoke RPC in that environment. |
INVALID_PAYLOAD | Malformed rpc:call body (not an object, or missing requestId / fnKey). |
KIND_MISMATCH | kind: 'service' used for a non-service entry (or the converse for express playground). |
Hooks such as registerPreInvoke may return a custom RpcResponse with their own label / error.code.
Strict clients should tolerate unknown code strings and treat them as generic failures.