Error codes
All Bissap SDK errors follow a consistent JSON shape:
{
"error": {
"code": "ERROR_CODE",
"message": "Human-readable description"
}
}Core Enforcement Codes (Stable Across SDKs)
These codes represent the stable enforcement surface and are consistent across Node and Python implementations.
| Code | HTTP | Description |
|---|---|---|
UNAUTHORIZED | 401 | Missing or invalid API key. |
FORBIDDEN | 403 | Key is valid but lacks the required scope for this intent. |
INTENT_NOT_FOUND | 404 | The requested intent is not registered. With strictIntents: true, returned for any unknown intent. |
INTENT_VALIDATION_ERROR | 400 | Payload failed schema validation. |
INTENT_RESULT_VALIDATION_ERROR | 500 | Handler returned output that failed result schema validation. |
VALIDATION_ERROR | 400 | General request validation failure. |
RATE_LIMITED | 429 | Per-key rate limit exceeded. Back off and retry. |
NOT_FOUND | 404 | Resource not found. |
Node-Specific Codes
| Code | HTTP | Description |
|---|---|---|
INTENT_HANDLER_ERROR | 500 | Intent handler threw an unhandled error. Message is intentionally generic. |
INTERNAL_ERROR | 500 | Unexpected server error. |
FORBIDDEN_SCOPE | 403 | Granular scope mismatch variant. |
Python-Specific Codes
| Code | HTTP | Description |
|---|---|---|
CLOUD_ERROR | 502 | Cloud control plane unreachable. |
CONFIG_ERROR | 500 | Missing required configuration. |
DENIED | 403 | Key denied via local denylist. |
INVALID_JSON | 400 | Request body is not valid JSON. |
Language implementations may expose additional internal classification codes. These do not change enforcement guarantees and may be unified in a future minor release.
Custom error codes from handlers
Intent handlers can throw errors with a .code property to return structured errors:
// In your intent handler:
throw Object.assign(new Error('Item not found'), { code: 'NOT_FOUND' });
// → { "error": { "code": "NOT_FOUND", "message": "Item not found" } }The Node SDK wraps handler errors in INTENT_HANDLER_ERROR by default. If the thrown error has a .code property, it's used instead, giving you clean, domain-specific error codes without leaking stack traces.