How to Handle Error Codes and Responses

This guide explains how to implement robust error handling for SAS-CBSD protocol responses as defined in WINNF-TS-0016.

Overview

All SAS responses include a response object with responseCode (integer) and responseMessage (string). Codes indicate success or specific failure reasons.

Proper handling ensures graceful recovery, prevents blacklisting, and improves user experience.

Key Bridge SAS Note: We log all error codes per CBSD/user for troubleshooting. Persistent errors may trigger support alerts.

Step 1: Common Response Structure

Every response (e.g., RegistrationResponse, GrantResponse) contains:

"response": {
  "responseCode": 0,
  "responseMessage": "Success"
}

Step 2: Key Error Code Categories

Success (0): Proceed normally.

Major Categories from WINNF-TS-0016:

Code Range	Category	Examples & Actions
0	SUCCESS	Continue to next step
100-199	AUTH/REGISTRATION	101 BLACKLISTED: Contact SAS admin; new cert/FCC ID needed
200-299	INQUIRY	202 INVALID_FREQUENCY: Adjust range (must be 3550-3700 MHz)
300-399	GRANT	301 INVALID_OPERATION_PARAM: Lower maxEirp or narrow range
400-499	GRANT (Failures)	400 GRANT_FAILURE: Retry with adjustments; check measurements
500-599	HEARTBEAT/DIRECTIVES	500 SUSPENDED_GRANT: Stop TX immediately; continue heartbeats
600-699	RELINQUISH	Rare; usually 0 or 103 MISSING_PARAM

Full Critical Codes Table

Code	Name	Meaning	Action Required
0	SUCCESS	Operation successful	Proceed
101	BLACKLISTED	Device/user blocked	Contact SAS provider; check FCC ID/serial
103	MISSING_PARAM	Required field absent	Add missing param (e.g., cbsdId, installationParam)
104	INVALID_VALUE	Param out of range (e.g., EIRP > capability)	Correct value; retry
105	UNSUPPORTED_PARAM	Param not recognized	Remove param
400	GRANT_FAILURE	Cannot grant (interference/DPA)	Lower EIRP; try different range; send measurements
401	INTERFERENCE	High interference detected	Include measReport; relocate if possible
500	SUSPENDED_GRANT	Grant suspended (e.g., DPA active)	Stop TX; heartbeat for resumption
501	TERMINATED_GRANT	Grant terminated	Relinquish; request new grant
502	UNSYNC_OP_PARAM	Params mismatch	Update to SAS-provided operationParam

Step 3: Implement Error Handling Logic

Pseudocode Example

def handle_response(response_json):
    for resp in response_json.get('responses', []):  # e.g., grantResponse array
        code = resp['response']['responseCode']
        msg = resp['response']['responseMessage']
        
        if code == 0:
            log.info(f"Success: {msg}")
            return "success"
        
        elif code in [103, 104, 105]:  # Param errors
            log.warn(f"Fix params: {code} - {msg}")
            # Auto-correct common issues (e.g., add missing fields)
            return "retry_fixed"
        
        elif code == 400:  # Grant failure
            log.warn(f"Grant fail: Reduce EIRP/range")
            adjust_request(resp)  # Lower maxEirp by 3dB, narrow range
            return "retry_adjusted"
        
        elif code == 500:
            log.error("SUSPEND TX!")
            stop_transmission()
            return "suspended"
        
        elif code == 501:
            log.error("TERMINATE!")
            relinquish_grant(resp['grantId'])
            return "terminated"
        
        else:
            log.error(f"Fatal: {code} - {msg}")
            alert_support()
            return "fatal"

Best Practices & Tips

Retry Strategy: Exponential backoff (1s, 2s, 4s) for transient codes (103-105, 400); max 3 retries.
Log Everything: Include full request/response JSON, timestamp, CBSD serial.
Auto-Recovery: Fix simple param errors automatically.
User Alerts: Map codes to user-friendly messages (e.g., "DPA active—stand by").
Metrics: Track code frequency per location/channel for optimization.
Key Bridge SAS: Send measurements even on errors—helps us diagnose and improve grants.

Common Issues & Troubleshooting

Issue	Likely Code(s)	Solution
Frequent GRANT_FAILURE (400)	400, 401	Enable measurements; check for nearby incumbents
Blacklisted after install	101	Verify CPI signature; contact support
Heartbeat TERMINATED (501)	501	DPA/ESC trigger; request new channel
Param errors on every retry	103/104	Validate JSON schema against WINNF-TS-0016 tables

Next Steps

Integrate into your main protocol loop
Test with simulated errors using SAS sandbox

[Image placeholder: Error code decision tree diagram]