| HTTP | Code | Meaning | Action |
|---|---|---|---|
| 400 | validation_error | Invalid payload, field mismatch, unsupported value, or malformed JSON. | Fix request fields and data format. |
| 401 | invalid_api_key / unauthorized | Missing or invalid Bearer token, or request does not satisfy internal auth/whitelist policy. | Use Authorization: Bearer <app_token> for direct runtime calls, or call through approved Onebrick internal path/source. |
| 401 | invalid_rotation_pin | The manual app-token rotation PIN is missing or invalid. | Retry from the FE rotation dialog with the correct PIN. |
| 403 | app_token_rotation_disabled | App token rotation PIN is not configured for the current runtime. | Configure the backend PIN, then rotate manually from FE. Normal deploys/upgrades must preserve tokens. |
| 403 | forbidden | Resource is outside allowed scope. | Use the exact device/path generated by the same flow. |
| 404 | not_found | Device/message/media not found. | Check identifiers and retry if eventual consistency applies. |
| 409 | device_not_connected / QR conflict | Device session is offline, still connected, or QR is still active. | Disconnect first, wait for QR expiry if needed, then retry the requested operation. |
| 413 | request_too_large | Request body exceeds configured limit. | Reduce payload size or use URL media source. |
| 429 | rate_limit_exceeded | Request throttled by limiter. | Retry with backoff. |
| 5xx | internal_error / upstream errors | Transient server/provider issue. | Retry with exponential backoff and idempotency keying. |
Note: internal host/IP whitelist policy applies to internal device-control routes. For webhook callback endpoints, use HMAC signature validation and optional ingress source filtering as independent controls.