# Computer Firewall **Page:** api/computer-firewall [Download Raw Markdown](./api/computer-firewall.md) --- # Computer Firewall Manage ingress and egress firewall rules for a computer. Use these endpoints to inspect the current rule set, add or remove rules, temporarily enable or disable rules, or reset the firewall to an open state. In the Hub, open Computers, select a computer and open Network. Its Firewall section lists the rules: use Add a rule or Presets to add rules, Turn off or Turn on and Delete on a rule, or Reset to no rules to remove every rule. Internet access, on the same tab, blocks the computer's outbound traffic with firewall rules. The cURL examples use `https://api.hoody.com` and send the Hoody account token in the `Authorization` header. Replace `{id}` with the computer ID. Rules are evaluated with `drop` and `reject` rules before `allow` rules, regardless of the order in which they were added. Traffic that matches no rule is allowed. As a result, `allow` rules alone do not restrict traffic. To permit only selected addresses, add `drop` or `reject` rules that cover the excluded ranges. Address filter fields support at most 512 characters per rule, so split long address lists across several rules. ## `GET /api/v1/computers/{id}/firewall/rules` Returns all ingress and egress firewall rules for a computer, along with the current rule count, serialized size, and applicable limits. ### Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `id` | path | string | Yes | Computer ID. | ### Request This endpoint does not accept a request body. ### Responses #### Successful response fields | Field | Type | Description | |---|---|---| | `statusCode` | number | HTTP status code. | | `message` | string | Result message. | | `data` | object | Firewall rule data. | | `data.ingress[]`, `data.egress[]` | array | Ingress and egress firewall rules. | | `data.ingress[].action`, `data.egress[].action` | string | Rule action. Allowed values: `allow`, `reject`, `drop`. | | `data.ingress[].protocol`, `data.egress[].protocol` | string | Network protocol. Allowed values: `tcp`, `udp`, `icmp4`. | | `data.ingress[].description`, `data.egress[].description` | string | Rule description. | | `data.ingress[].destination_port`, `data.egress[].destination_port` | string | Destination port, port range, or comma-separated port list. | | `data.ingress[].source`, `data.egress[].source` | string | Source IPv4 address or CIDR range. | | `data.ingress[].destination`, `data.egress[].destination` | string | Destination IPv4 address or CIDR range. | | `data.ingress[].source_port`, `data.egress[].source_port` | string | Source port, port range, or comma-separated port list. | | `data.ingress[].state`, `data.egress[].state` | string | Rule state. Allowed values: `enabled`, `disabled`. Default: `"enabled"`. | | `data.ingress[].icmp_type`, `data.egress[].icmp_type` | string | ICMP type number for `icmp4` rules. | | `data.ingress[].icmp_code`, `data.egress[].icmp_code` | string | ICMP code number for `icmp4` rules. | | `data.ingress[].direction`, `data.egress[].direction` | string | Rule direction. Allowed values: `ingress`, `egress`. | | `data.rule_count` | number | Current number of ingress and egress rules. Advisory. | | `data.byte_count` | number | Serialized size of the current rule set in bytes. Advisory. | | `data.max_rules` | number | Maximum number of ingress and egress rules allowed on the computer. | | `data.max_bytes` | number | Maximum serialized size of the computer's rule set in bytes. | Media type: application/json ```json { "statusCode": 200, "message": "Rules retrieved successfully", "data": { "ingress": [ { "action": "allow", "protocol": "tcp", "description": "Allow HTTPS traffic", "destination_port": "443", "source": "0.0.0.0/0", "state": "enabled" }, { "action": "allow", "protocol": "icmp4", "description": "Allow ping from any source", "source": "0.0.0.0/0", "state": "enabled", "icmp_type": "8", "icmp_code": "0" } ], "egress": [ { "action": "allow", "protocol": "tcp", "description": "Allow outbound HTTPS", "destination_port": "443", "destination": "0.0.0.0/0", "state": "enabled" }, { "action": "drop", "protocol": "tcp", "description": "Block outbound SMTP", "destination_port": "25", "destination": "0.0.0.0/0", "state": "enabled" } ] } } ``` Media type: application/json The body contains `statusCode`, `error`, and `message`. ```json { "statusCode": 401, "error": "MISSING_TOKEN", "message": "Authorization header is required" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `MISSING_TOKEN` | Authentication token missing | The request carries no Authorization header, or the header holds no token. | Send an Authorization header as `Bearer ` with a sign-in token or an auth token. | | `INVALID_TOKEN` | Invalid authentication token | The provided authentication token is malformed or invalid. | Obtain a new token by logging in again or using a valid auth token. | | `TOKEN_EXPIRED` | Authentication token expired | The sign-in token (JWT) has expired. An expired auth token is refused with `INVALID_TOKEN` instead. | Sign in again, or refresh the session. | | `AUTH_TOKEN_LINEAGE_REVOKED` | Parent auth token no longer valid | The auth token was created by another auth token, and that token, or one above it, has been revoked, disabled, or has expired, so this token no longer authenticates. | Create a new auth token from a valid one, or sign in again. | | `INVALID_CREDENTIALS` | Invalid credentials | The provided username or email address, or password, is incorrect. | Verify your credentials and try again, or use the password reset feature. | | `EMAIL_NOT_VERIFIED` | Email not verified | The password is correct, but the account's email address is not verified yet. HTTP Basic authentication can return this error on any operation without the email. | Complete email verification, request another verification link, or complete a password reset. | | `INVALID_OTP_CODE` | Invalid OTP code | The provided 2FA code is incorrect or has expired. | Generate a new code from your authenticator app and try again. | Media type: application/json The body contains `statusCode`, `error`, and `message`. ```json { "statusCode": 403, "error": "INSUFFICIENT_PERMISSIONS", "message": "Insufficient permissions" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `INSUFFICIENT_PERMISSIONS` | Insufficient permissions | You do not have the required permissions to perform this action. | Ask the resource owner to grant you access. | | `ACCOUNT_BANNED` | Account banned | Your account has been banned and cannot access this resource. | Contact support for information about your account status. | Media type: application/json The computer or its project does not exist. A computer you do not have access to is refused with `403`. The body contains `statusCode`, `error`, and `message`. ```json { "statusCode": 404, "error": "Not Found", "message": "Computer not found" } ``` Media type: application/json The body contains `statusCode`, `error`, `message`, and `data`. For a schema failure, each `data` entry contains `instancePath`, `schemaPath`, `keyword`, `params`, and `message`. ```json { "statusCode": 422, "error": "Validation Error", "message": "Validation failed: /id must be string", "data": [ { "instancePath": "/id", "schemaPath": "#/properties/id/type", "keyword": "type", "params": { "type": "string" }, "message": "must be string" } ] } ``` Media type: application/json The body contains `statusCode`, `error`, and `message`. ```json { "statusCode": 429, "error": "Too Many Requests", "message": "Rate limit exceeded for this endpoint. Please try again later." } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `RATE_LIMIT_EXCEEDED` | Rate limit exceeded | Too many requests of this kind in a short time, counted per account, auth token, or address. The request was not carried out. | Wait the number of seconds in the `Retry-After` header, then try again. | The `Retry-After` header contains the number of seconds to wait before retrying. Media type: application/json The firewall rules could not be read. Nothing was changed. The body contains `statusCode`, `error`, and `message`. ```json { "statusCode": 500, "error": "Internal Server Error", "message": "Failed to retrieve firewall rules" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `INTERNAL_SERVER_ERROR` | Internal server error | The firewall rules could not be read. Nothing was changed. | Retry. If the problem persists, contact support. | Media type: application/json The firewall could not be reached for a moment. Nothing was changed. Retry after the `Retry-After` header. The body contains `statusCode`, `error`, `message`, and `data`. ```json { "statusCode": 503, "error": "FIREWALL_HOST_UNAVAILABLE", "message": "This computer's firewall rules could not be read right now. Retry shortly.", "data": { "field": "firewall", "computer_id": "507f1f77bcf86cd799439011" } } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `FIREWALL_HOST_UNAVAILABLE` | Firewall temporarily unavailable | The computer's firewall could not be reached for a moment, for example because its server is busy. Nothing was changed. | Retry after the number of seconds in the `Retry-After` header. | ### Usage ```bash curl --request GET \ --url 'https://api.hoody.com/api/v1/computers/{id}/firewall/rules' \ --header "Authorization: Bearer $HOODY_TOKEN" ``` ```typescript import { HoodyClient } from 'hoody-sdk'; const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN }); const { data } = await client.api.firewall.listRules("c_abc123def456"); console.log(data.ingress); console.log(data.egress); ``` ## `POST /api/v1/computers/{id}/firewall/ingress` Adds an ingress rule to control traffic that can reach a computer. `destination_port` is required for `tcp` and `udp` rules and is not allowed with `icmp4`. A rule that already exists returns `200`; a newly added rule returns `201`. The Hoody kits, including terminal and files, are reached over TCP on fixed ports inside the computer. By default, these ports are `4`, `5`, `44`-`46`, `48`, `50`, `55`, `59`-`62`, `74`-`78`, `3971`, `3998`, `3999`, and `23333`. A `drop` or `reject` rule covering one of these ports blocks the kits for matching traffic while the rule is enabled. The rule is still added, and the response includes a `FIREWALL_RULE_COVERS_KIT_PORTS` warning. ### Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `id` | path | string | Yes | Computer ID. | ### Request body | Name | Type | Required | Description | |---|---|---|---| | `action` | string | Yes | Action to take. Allowed values: `allow`, `reject`, `drop`. | | `protocol` | string | Yes | Network protocol. Allowed values: `tcp`, `udp`, `icmp4`. | | `description` | string | Yes | Human-readable rule description. Maximum length: 255 characters. | | `destination_port` | string | No | Port number from 1 through 65535, a low-to-high range, or a comma-separated list. Required for `tcp` and `udp`, and not allowed with `icmp4`. Maximum length: 64 characters. | | `source` | string | No | Source IPv4 address or CIDR range, or a comma-separated list. Use `0.0.0.0/0` for any source. IPv6 is not supported. Maximum length: 512 characters. | | `source_port` | string | No | Source port filter. Maximum length: 64 characters. | | `state` | string | No | Rule state. Allowed values: `enabled`, `disabled`. Default: `"enabled"`. | | `icmp_type` | string | No | ICMP type number, such as `8` for an echo request. Maximum length: 8 characters. | | `icmp_code` | string | No | ICMP code number. Maximum length: 8 characters. | ### Responses #### Successful response fields | Field | Type | Description | |---|---|---| | `statusCode` | number | HTTP status code. | | `message` | string | Result message. | | `warnings` | array | Warnings about the added rule. | | `warnings[].code` | string | Warning code. Allowed value: `FIREWALL_RULE_COVERS_KIT_PORTS`. | | `warnings[].message` | string | Warning message. | | `warnings[].ports` | array | Hoody kit ports covered by the rule. | | `data` | object | The complete ingress and egress rule set, or duplicate rule details when the rule already exists. | Media type: application/json ```json { "statusCode": 200, "message": "Rule already exists (duplicate)", "data": { "action": "allow", "protocol": "tcp", "description": "Allow HTTPS traffic", "destination_port": "443", "source": "0.0.0.0/0", "state": "enabled", "duplicate": true, "duplicate_of": { "direction": "ingress", "index": 0 } } } ``` Media type: application/json ```json { "statusCode": 201, "message": "Ingress rule added successfully", "data": { "ingress": [ { "action": "allow", "protocol": "tcp", "description": "Allow HTTPS traffic", "destination_port": "443", "source": "0.0.0.0/0", "state": "enabled" } ], "egress": [] } } ``` Media type: application/json The body contains `statusCode`, `error`, `message`, and `data`. ```json { "statusCode": 400, "error": "INVALID_RULE_DEFINITION", "message": "Invalid firewall rule definition." } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `INVALID_RULE_DEFINITION` | Invalid Firewall Rule | The firewall rule definition is invalid: a field required by the protocol is missing, such as `destination_port` for TCP or UDP; a field is not allowed with the protocol, such as ports with `icmp4` or `icmp_type` with TCP or UDP; or a value is malformed. `data.field` names the field. The rule was not added or changed. | Correct the field named in `data.field`. Ports are 1-65535, ranges are written low-high, and addresses are comma-separated IPv4 addresses or CIDR ranges. | | `COMPUTER_FIREWALL_RULE_LIMIT` | Computer firewall rule limit reached | The computer already holds the maximum number of firewall rules allowed, with ingress and egress counted together. The applicable limit is returned as `max_rules` when listing firewall rules. | Remove an existing firewall rule on this computer before adding a new one. | | `COMPUTER_FIREWALL_BYTES_LIMIT` | Computer firewall rule size limit reached | The computer's firewall rules have reached their total serialized size budget. This can be hit below the rule-count limit when individual rules are large, such as rules with long descriptions or address lists. The applicable limit is returned as `max_bytes` when listing firewall rules. | Remove rules, or shorten descriptions and address lists, before adding a new rule. | Media type: application/json The body contains `statusCode`, `error`, and `message`. ```json { "statusCode": 401, "error": "MISSING_TOKEN", "message": "Authorization header is required" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `MISSING_TOKEN` | Authentication token missing | The request carries no Authorization header, or the header holds no token. | Send an Authorization header as `Bearer ` with a sign-in token or an auth token. | | `INVALID_TOKEN` | Invalid authentication token | The provided authentication token is malformed or invalid. | Obtain a new token by logging in again or using a valid auth token. | | `TOKEN_EXPIRED` | Authentication token expired | The sign-in token (JWT) has expired. An expired auth token is refused with `INVALID_TOKEN` instead. | Sign in again, or refresh the session. | | `AUTH_TOKEN_LINEAGE_REVOKED` | Parent auth token no longer valid | The auth token was created by another auth token, and that token, or one above it, has been revoked, disabled, or has expired, so this token no longer authenticates. | Create a new auth token from a valid one, or sign in again. | | `INVALID_CREDENTIALS` | Invalid credentials | The provided username or email address, or password, is incorrect. | Verify your credentials and try again, or use the password reset feature. | | `EMAIL_NOT_VERIFIED` | Email not verified | The password is correct, but the account's email address is not verified yet. HTTP Basic authentication can return this error on any operation without the email. | Complete email verification, request another verification link, or complete a password reset. | | `INVALID_OTP_CODE` | Invalid OTP code | The provided 2FA code is incorrect or has expired. | Generate a new code from your authenticator app and try again. | Media type: application/json The body contains `statusCode`, `error`, and `message`. ```json { "statusCode": 403, "error": "INSUFFICIENT_PERMISSIONS", "message": "Insufficient permissions" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `computer_quarantined` | Computer is quarantined | The computer is held for review, so its firewall cannot change, including for an admin. Nothing was changed. | Contact support. | | `INSUFFICIENT_PERMISSIONS` | Insufficient permissions | You do not have the required permissions to perform this action. | Ask the resource owner to grant you access. | | `ACCOUNT_BANNED` | Account banned | Your account has been banned and cannot access this resource. | Contact support for information about your account status. | Media type: application/json The computer or its project does not exist. A computer you do not have access to is refused with `403`. The body contains `statusCode`, `error`, and `message`. ```json { "statusCode": 404, "error": "Not Found", "message": "Computer not found" } ``` Media type: application/json The body contains `statusCode`, `error`, `message`, and `data`. ```json { "statusCode": 409, "error": "computer_finalizing", "message": "This computer is still being set up. Retry in a few seconds." } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `computer_finalizing` | Computer is still being set up | The computer is still being set up and refuses changes until that completes. | Retry in a few seconds. | | `COMPUTER_EXPIRED` | Computer has expired | The computer expired when its server ended or was reinstalled, so its firewall cannot change. Nothing was changed. | The computer cannot be changed again. Delete it, then create a new computer. | | `OPERATION_STATE_CONFLICT` | Computer state does not allow firewall changes | The computer is being created or deleted, or was deleted, so its firewall cannot change. The message names the status. Nothing was changed. | Retry once the computer has been created. A deleted computer cannot be changed. | | `SUBSERVER_DORMANT` | Subserver is not active | The computer is on a paid subserver whose subscription is not active, or a change to it is in progress, so its firewall cannot change. `data.reason` is `not_active`, `operation_in_flight`, or `no_subscription`. Nothing was changed. | Retry once the subserver is active again. | Media type: application/json The body contains `statusCode`, `error`, `message`, and `data`. For a schema failure, each `data` entry contains `instancePath`, `schemaPath`, `keyword`, `params`, and `message`. ```json { "statusCode": 422, "error": "Validation Error", "message": "Validation failed: /action must be string", "data": [ { "instancePath": "/action", "schemaPath": "#/properties/action/type", "keyword": "type", "params": { "type": "string" }, "message": "must be string" } ] } ``` Media type: application/json The body contains `statusCode`, `error`, and `message`. ```json { "statusCode": 429, "error": "Too Many Requests", "message": "Rate limit exceeded for this endpoint. Please try again later." } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `RATE_LIMIT_EXCEEDED` | Rate limit exceeded | Too many requests of this kind in a short time, counted per account, auth token, or address. The request was not carried out. | Wait the number of seconds in the `Retry-After` header, then try again. | The `Retry-After` header contains the number of seconds to wait before retrying. Media type: application/json The firewall change failed unexpectedly. It may or may not have been applied. The body contains `statusCode`, `error`, `message`, and `data`, where `data` is any JSON value. ```json { "statusCode": 500, "error": "Internal Server Error", "message": "Failed to add ingress firewall rule" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `INTERNAL_SERVER_ERROR` | Internal server error | The firewall change failed unexpectedly. It may or may not have been applied. | List the rules to see the current state, then retry if needed. If the problem persists, contact support. | Media type: application/json The firewall could not be reached for a moment. Nothing was changed. Retry after the `Retry-After` header. The body contains `statusCode`, `error`, `message`, and `data`. ```json { "statusCode": 503, "error": "FIREWALL_INVENTORY_UNAVAILABLE", "message": "Unable to verify this computer's firewall rules. No changes were made.", "data": { "field": "firewall_inventory", "computer_id": "507f1f77bcf86cd799439011" } } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `FIREWALL_INVENTORY_UNAVAILABLE` | Firewall inventory unavailable | The computer's current firewall rules could not be read, so the rule limit could not be checked. No rule was added. | Retry shortly. If it persists, the hosting server may be unreachable. | | `FIREWALL_HOST_UNAVAILABLE` | Firewall temporarily unavailable | The computer's firewall could not be reached for a moment, for example because its server is busy. Nothing was changed. | Retry after the number of seconds in the `Retry-After` header. | ### Usage ```bash curl --request POST \ --url 'https://api.hoody.com/api/v1/computers/{id}/firewall/ingress' \ --header "Authorization: Bearer $HOODY_TOKEN" \ --header "Content-Type: application/json" \ --data '{ "action": "allow", "protocol": "tcp", "description": "Allow SSH from office", "destination_port": "22", "source": "203.0.113.5/32" }' ``` ```typescript import { HoodyClient } from 'hoody-sdk'; const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN }); const response = await client.api.firewall.ingress.create("c_abc123def456", { action: "allow", protocol: "tcp", description: "Allow SSH from office", destination_port: "22", source: "203.0.113.5/32", }); console.log(response); ``` ## `POST /api/v1/computers/{id}/firewall/egress` Adds an egress rule to control traffic sent by a computer. `destination_port` is required for `tcp` and `udp` rules and is not allowed with `icmp4`. A rule that already exists returns `200`; a newly added rule returns `201`. ### Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `id` | path | string | Yes | Computer ID. | ### Request body | Name | Type | Required | Description | |---|---|---|---| | `action` | string | Yes | Action to take. Allowed values: `allow`, `reject`, `drop`. | | `protocol` | string | Yes | Network protocol. Allowed values: `tcp`, `udp`, `icmp4`. | | `description` | string | Yes | Human-readable rule description. Maximum length: 255 characters. | | `destination_port` | string | No | Port number from 1 through 65535, a low-to-high range, or a comma-separated list. Required for `tcp` and `udp`, and not allowed with `icmp4`. Maximum length: 64 characters. | | `destination` | string | No | Destination IPv4 address or CIDR range, or a comma-separated list. Use `0.0.0.0/0` for any destination. IPv6 is not supported. Maximum length: 512 characters. | | `source_port` | string | No | Source port filter. Maximum length: 64 characters. | | `state` | string | No | Rule state. Allowed values: `enabled`, `disabled`. Default: `"enabled"`. | | `icmp_type` | string | No | ICMP type number. Maximum length: 8 characters. | | `icmp_code` | string | No | ICMP code number. Maximum length: 8 characters. | ### Responses #### Successful response fields | Field | Type | Description | |---|---|---| | `statusCode` | number | HTTP status code. | | `message` | string | Result message. | | `data` | object | The complete ingress and egress rule set, or duplicate rule details when the rule already exists. | Media type: application/json ```json { "statusCode": 200, "message": "Rule already exists (duplicate)", "data": { "action": "allow", "protocol": "tcp", "description": "Allow outbound HTTPS", "destination_port": "443", "destination": "0.0.0.0/0", "state": "enabled", "duplicate": true, "duplicate_of": { "direction": "egress", "index": 0 } } } ``` Media type: application/json ```json { "statusCode": 201, "message": "Egress rule added successfully", "data": { "ingress": [], "egress": [ { "action": "allow", "protocol": "tcp", "description": "Allow outbound HTTPS", "destination_port": "443", "destination": "0.0.0.0/0", "state": "enabled" } ] } } ``` Media type: application/json The body contains `statusCode`, `error`, `message`, and `data`. ```json { "statusCode": 400, "error": "INVALID_RULE_DEFINITION", "message": "Invalid firewall rule definition." } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `INVALID_RULE_DEFINITION` | Invalid Firewall Rule | The firewall rule definition is invalid: a field required by the protocol is missing, such as `destination_port` for TCP or UDP; a field is not allowed with the protocol, such as ports with `icmp4` or `icmp_type` with TCP or UDP; or a value is malformed. `data.field` names the field. The rule was not added or changed. | Correct the field named in `data.field`. Ports are 1-65535, ranges are written low-high, and addresses are comma-separated IPv4 addresses or CIDR ranges. | | `COMPUTER_FIREWALL_RULE_LIMIT` | Computer firewall rule limit reached | The computer already holds the maximum number of firewall rules allowed, with ingress and egress counted together. The applicable limit is returned as `max_rules` when listing firewall rules. | Remove an existing firewall rule on this computer before adding a new one. | | `COMPUTER_FIREWALL_BYTES_LIMIT` | Computer firewall rule size limit reached | The computer's firewall rules have reached their total serialized size budget. This can be hit below the rule-count limit when individual rules are large, such as rules with long descriptions or address lists. The applicable limit is returned as `max_bytes` when listing firewall rules. | Remove rules, or shorten descriptions and address lists, before adding a new rule. | Media type: application/json The body contains `statusCode`, `error`, and `message`. ```json { "statusCode": 401, "error": "MISSING_TOKEN", "message": "Authorization header is required" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `MISSING_TOKEN` | Authentication token missing | The request carries no Authorization header, or the header holds no token. | Send an Authorization header as `Bearer ` with a sign-in token or an auth token. | | `INVALID_TOKEN` | Invalid authentication token | The provided authentication token is malformed or invalid. | Obtain a new token by logging in again or using a valid auth token. | | `TOKEN_EXPIRED` | Authentication token expired | The sign-in token (JWT) has expired. An expired auth token is refused with `INVALID_TOKEN` instead. | Sign in again, or refresh the session. | | `AUTH_TOKEN_LINEAGE_REVOKED` | Parent auth token no longer valid | The auth token was created by another auth token, and that token, or one above it, has been revoked, disabled, or has expired, so this token no longer authenticates. | Create a new auth token from a valid one, or sign in again. | | `INVALID_CREDENTIALS` | Invalid credentials | The provided username or email address, or password, is incorrect. | Verify your credentials and try again, or use the password reset feature. | | `EMAIL_NOT_VERIFIED` | Email not verified | The password is correct, but the account's email address is not verified yet. HTTP Basic authentication can return this error on any operation without the email. | Complete email verification, request another verification link, or complete a password reset. | | `INVALID_OTP_CODE` | Invalid OTP code | The provided 2FA code is incorrect or has expired. | Generate a new code from your authenticator app and try again. | Media type: application/json The body contains `statusCode`, `error`, and `message`. ```json { "statusCode": 403, "error": "INSUFFICIENT_PERMISSIONS", "message": "Insufficient permissions" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `computer_quarantined` | Computer is quarantined | The computer is held for review, so its firewall cannot change, including for an admin. Nothing was changed. | Contact support. | | `INSUFFICIENT_PERMISSIONS` | Insufficient permissions | You do not have the required permissions to perform this action. | Ask the resource owner to grant you access. | | `ACCOUNT_BANNED` | Account banned | Your account has been banned and cannot access this resource. | Contact support for information about your account status. | Media type: application/json The computer or its project does not exist. A computer you do not have access to is refused with `403`. The body contains `statusCode`, `error`, and `message`. ```json { "statusCode": 404, "error": "Not Found", "message": "Computer not found" } ``` Media type: application/json The body contains `statusCode`, `error`, `message`, and `data`. ```json { "statusCode": 409, "error": "computer_finalizing", "message": "This computer is still being set up. Retry in a few seconds." } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `computer_finalizing` | Computer is still being set up | The computer is still being set up and refuses changes until that completes. | Retry in a few seconds. | | `COMPUTER_EXPIRED` | Computer has expired | The computer expired when its server ended or was reinstalled, so its firewall cannot change. Nothing was changed. | The computer cannot be changed again. Delete it, then create a new computer. | | `OPERATION_STATE_CONFLICT` | Computer state does not allow firewall changes | The computer is being created or deleted, or was deleted, so its firewall cannot change. The message names the status. Nothing was changed. | Retry once the computer has been created. A deleted computer cannot be changed. | | `SUBSERVER_DORMANT` | Subserver is not active | The computer is on a paid subserver whose subscription is not active, or a change to it is in progress, so its firewall cannot change. `data.reason` is `not_active`, `operation_in_flight`, or `no_subscription`. Nothing was changed. | Retry once the subserver is active again. | Media type: application/json The body contains `statusCode`, `error`, `message`, and `data`. For a schema failure, each `data` entry contains `instancePath`, `schemaPath`, `keyword`, `params`, and `message`. ```json { "statusCode": 422, "error": "Validation Error", "message": "Validation failed: /action must be string", "data": [ { "instancePath": "/action", "schemaPath": "#/properties/action/type", "keyword": "type", "params": { "type": "string" }, "message": "must be string" } ] } ``` Media type: application/json The body contains `statusCode`, `error`, and `message`. ```json { "statusCode": 429, "error": "Too Many Requests", "message": "Rate limit exceeded for this endpoint. Please try again later." } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `RATE_LIMIT_EXCEEDED` | Rate limit exceeded | Too many requests of this kind in a short time, counted per account, auth token, or address. The request was not carried out. | Wait the number of seconds in the `Retry-After` header, then try again. | The `Retry-After` header contains the number of seconds to wait before retrying. Media type: application/json The firewall change failed unexpectedly. It may or may not have been applied. The body contains `statusCode`, `error`, `message`, and `data`, where `data` is any JSON value. ```json { "statusCode": 500, "error": "Internal Server Error", "message": "Failed to add egress firewall rule" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `INTERNAL_SERVER_ERROR` | Internal server error | The firewall change failed unexpectedly. It may or may not have been applied. | List the rules to see the current state, then retry if needed. If the problem persists, contact support. | Media type: application/json The firewall could not be reached for a moment. Nothing was changed. Retry after the `Retry-After` header. The body contains `statusCode`, `error`, `message`, and `data`. ```json { "statusCode": 503, "error": "FIREWALL_INVENTORY_UNAVAILABLE", "message": "Unable to verify this computer's firewall rules. No changes were made.", "data": { "field": "firewall_inventory", "computer_id": "507f1f77bcf86cd799439011" } } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `FIREWALL_INVENTORY_UNAVAILABLE` | Firewall inventory unavailable | The computer's current firewall rules could not be read, so the rule limit could not be checked. No rule was added. | Retry shortly. If it persists, the hosting server may be unreachable. | | `FIREWALL_HOST_UNAVAILABLE` | Firewall temporarily unavailable | The computer's firewall could not be reached for a moment, for example because its server is busy. Nothing was changed. | Retry after the number of seconds in the `Retry-After` header. | ### Usage ```bash curl --request POST \ --url 'https://api.hoody.com/api/v1/computers/{id}/firewall/egress' \ --header "Authorization: Bearer $HOODY_TOKEN" \ --header "Content-Type: application/json" \ --data '{ "action": "drop", "protocol": "tcp", "description": "Block outbound SMTP", "destination_port": "25", "destination": "0.0.0.0/0" }' ``` ```typescript import { HoodyClient } from 'hoody-sdk'; const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN }); const response = await client.api.firewall.egress.create("c_abc123def456", { action: "drop", protocol: "tcp", description: "Block outbound SMTP", destination_port: "25", destination: "0.0.0.0/0", }); console.log(response); ``` ## `PATCH /api/v1/computers/{id}/firewall/ingress` Enables or disables an ingress rule without deleting it. Supply filters that identify the rule to update. ### Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `id` | path | string | Yes | Computer ID. | ### Request body | Name | Type | Required | Description | |---|---|---|---| | `state` | string | Yes | New rule state. Allowed values: `enabled`, `disabled`. The TypeScript SDK methods set this value automatically. | | `action` | string | No | Match rules with this action. Allowed values: `allow`, `reject`, `drop`. | | `protocol` | string | No | Match rules with this protocol. Allowed values: `tcp`, `udp`, `icmp4`. | | `destination_port` | string | No | Match this destination port, range, or comma-separated list. Maximum length: 64 characters. | | `source_port` | string | No | Match this source port, range, or comma-separated list. Maximum length: 64 characters. | | `source` | string | No | Match this source IPv4 address or CIDR range. Maximum length: 512 characters. | | `description` | string | No | Match this rule description. Maximum length: 255 characters. | | `icmp_type` | string | No | Match this ICMP type number. Maximum length: 8 characters. | | `icmp_code` | string | No | Match this ICMP code number. Maximum length: 8 characters. | ### Responses #### Successful response fields | Field | Type | Description | |---|---|---| | `statusCode` | number | HTTP status code. | | `message` | string | Result message. | | `data.direction` | string | Direction of the updated rule. | | `data.new_state` | string | New state of the rule. | | `data.updated` | object | Updated rule. | | `data.updated.action` | string | Rule action. Allowed values: `allow`, `reject`, `drop`. | | `data.updated.protocol` | string | Network protocol. Allowed values: `tcp`, `udp`, `icmp4`. | | `data.updated.description` | string | Rule description. | | `data.updated.destination_port` | string | Destination port, range, or comma-separated list. | | `data.updated.source` | string | Source IPv4 address or CIDR range. | | `data.updated.source_port` | string | Source port, range, or comma-separated list. | | `data.updated.state` | string | Rule state. Allowed values: `enabled`, `disabled`. Default: `"enabled"`. | | `data.updated.icmp_type` | string | ICMP type number. | | `data.updated.icmp_code` | string | ICMP code number. | Media type: application/json ```json { "statusCode": 200, "message": "Ingress rule state toggled successfully", "data": { "direction": "ingress", "new_state": "disabled", "updated": { "action": "allow", "protocol": "tcp", "description": "Allow HTTPS traffic", "destination_port": "443", "source": "0.0.0.0/0", "state": "disabled" } } } ``` Media type: application/json The body contains `statusCode`, `error`, and `message`. ```json { "statusCode": 401, "error": "MISSING_TOKEN", "message": "Authorization header is required" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `MISSING_TOKEN` | Authentication token missing | The request carries no Authorization header, or the header holds no token. | Send an Authorization header as `Bearer ` with a sign-in token or an auth token. | | `INVALID_TOKEN` | Invalid authentication token | The provided authentication token is malformed or invalid. | Obtain a new token by logging in again or using a valid auth token. | | `TOKEN_EXPIRED` | Authentication token expired | The sign-in token (JWT) has expired. An expired auth token is refused with `INVALID_TOKEN` instead. | Sign in again, or refresh the session. | | `AUTH_TOKEN_LINEAGE_REVOKED` | Parent auth token no longer valid | The auth token was created by another auth token, and that token, or one above it, has been revoked, disabled, or has expired, so this token no longer authenticates. | Create a new auth token from a valid one, or sign in again. | | `INVALID_CREDENTIALS` | Invalid credentials | The provided username or email address, or password, is incorrect. | Verify your credentials and try again, or use the password reset feature. | | `EMAIL_NOT_VERIFIED` | Email not verified | The password is correct, but the account's email address is not verified yet. HTTP Basic authentication can return this error on any operation without the email. | Complete email verification, request another verification link, or complete a password reset. | | `INVALID_OTP_CODE` | Invalid OTP code | The provided 2FA code is incorrect or has expired. | Generate a new code from your authenticator app and try again. | Media type: application/json The body contains `statusCode`, `error`, and `message`. ```json { "statusCode": 403, "error": "INSUFFICIENT_PERMISSIONS", "message": "Insufficient permissions" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `computer_quarantined` | Computer is quarantined | The computer is held for review, so its firewall cannot change, including for an admin. Nothing was changed. | Contact support. | | `INSUFFICIENT_PERMISSIONS` | Insufficient permissions | You do not have the required permissions to perform this action. | Ask the resource owner to grant you access. | | `ACCOUNT_BANNED` | Account banned | Your account has been banned and cannot access this resource. | Contact support for information about your account status. | Media type: application/json The computer or its project does not exist. A computer you do not have access to is refused with `403`. The body contains `statusCode`, `error`, and `message`. ```json { "statusCode": 404, "error": "Not Found", "message": "Computer not found" } ``` Media type: application/json The body contains `statusCode`, `error`, `message`, and `data`. ```json { "statusCode": 409, "error": "computer_finalizing", "message": "This computer is still being set up. Retry in a few seconds." } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `computer_finalizing` | Computer is still being set up | The computer is still being set up and refuses changes until that completes. | Retry in a few seconds. | | `COMPUTER_EXPIRED` | Computer has expired | The computer expired when its server ended or was reinstalled, so its firewall cannot change. Nothing was changed. | The computer cannot be changed again. Delete it, then create a new computer. | | `OPERATION_STATE_CONFLICT` | Computer state does not allow firewall changes | The computer is being created or deleted, or was deleted, so its firewall cannot change. The message names the status. Nothing was changed. | Retry once the computer has been created. A deleted computer cannot be changed. | | `SUBSERVER_DORMANT` | Subserver is not active | The computer is on a paid subserver whose subscription is not active, or a change to it is in progress, so its firewall cannot change. `data.reason` is `not_active`, `operation_in_flight`, or `no_subscription`. Nothing was changed. | Retry once the subserver is active again. | Media type: application/json The body contains `statusCode`, `error`, `message`, and `data`. For a schema failure, each `data` entry contains `instancePath`, `schemaPath`, `keyword`, `params`, and `message`. ```json { "statusCode": 422, "error": "Validation Error", "message": "Validation failed: /state must be string", "data": [ { "instancePath": "/state", "schemaPath": "#/properties/state/type", "keyword": "type", "params": { "type": "string" }, "message": "must be string" } ] } ``` Media type: application/json The body contains `statusCode`, `error`, and `message`. ```json { "statusCode": 429, "error": "Too Many Requests", "message": "Rate limit exceeded for this endpoint. Please try again later." } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `RATE_LIMIT_EXCEEDED` | Rate limit exceeded | Too many requests of this kind in a short time, counted per account, auth token, or address. The request was not carried out. | Wait the number of seconds in the `Retry-After` header, then try again. | The `Retry-After` header contains the number of seconds to wait before retrying. Media type: application/json The firewall change failed unexpectedly. It may or may not have been applied. The body contains `statusCode`, `error`, `message`, and `data`, where `data` is any JSON value. ```json { "statusCode": 500, "error": "Internal Server Error", "message": "Failed to toggle ingress firewall rule" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `INTERNAL_SERVER_ERROR` | Internal server error | The firewall change failed unexpectedly. It may or may not have been applied. | List the rules to see the current state, then retry if needed. If the problem persists, contact support. | Media type: application/json The firewall could not be reached for a moment. Nothing was changed. Retry after the `Retry-After` header. The body contains `statusCode`, `error`, `message`, and `data`. ```json { "statusCode": 503, "error": "FIREWALL_HOST_UNAVAILABLE", "message": "This computer's firewall rules could not be changed right now. No changes were made. Retry shortly.", "data": { "field": "firewall", "computer_id": "507f1f77bcf86cd799439011" } } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `FIREWALL_HOST_UNAVAILABLE` | Firewall temporarily unavailable | The computer's firewall could not be reached for a moment, for example because its server is busy. Nothing was changed. | Retry after the number of seconds in the `Retry-After` header. | ### Usage ```bash curl --request PATCH \ --url 'https://api.hoody.com/api/v1/computers/{id}/firewall/ingress' \ --header "Authorization: Bearer $HOODY_TOKEN" \ --header "Content-Type: application/json" \ --data '{ "state": "enabled", "action": "allow", "protocol": "tcp", "destination_port": "443", "source": "203.0.113.5/32" }' ``` ```typescript import { HoodyClient } from 'hoody-sdk'; const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN }); const response = await client.api.firewall.ingress.enable("c_abc123def456", { action: "allow", protocol: "tcp", destination_port: "443", source: "203.0.113.5/32", }); console.log(response); ``` The SDK state methods are: - `client.api.firewall.ingress.enable(id, data)` sets `state: "enabled"`. - `client.api.firewall.ingress.disable(id, data)` sets `state: "disabled"`. ## `PATCH /api/v1/computers/{id}/firewall/egress` Enables or disables an egress rule without deleting it. Supply filters that identify the rule to update. ### Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `id` | path | string | Yes | Computer ID. | ### Request body | Name | Type | Required | Description | |---|---|---|---| | `state` | string | Yes | New rule state. Allowed values: `enabled`, `disabled`. The TypeScript SDK methods set this value automatically. | | `action` | string | No | Match rules with this action. Allowed values: `allow`, `reject`, `drop`. | | `protocol` | string | No | Match rules with this protocol. Allowed values: `tcp`, `udp`, `icmp4`. | | `destination_port` | string | No | Match this destination port, range, or comma-separated list. Maximum length: 64 characters. | | `source_port` | string | No | Match this source port, range, or comma-separated list. Maximum length: 64 characters. | | `destination` | string | No | Match this destination IPv4 address or CIDR range. Maximum length: 512 characters. | | `description` | string | No | Match this rule description. Maximum length: 255 characters. | | `icmp_type` | string | No | Match this ICMP type number. Maximum length: 8 characters. | | `icmp_code` | string | No | Match this ICMP code number. Maximum length: 8 characters. | ### Responses #### Successful response fields | Field | Type | Description | |---|---|---| | `statusCode` | number | HTTP status code. | | `message` | string | Result message. | | `data.direction` | string | Direction of the updated rule. | | `data.new_state` | string | New state of the rule. | | `data.updated` | object | Updated rule. | | `data.updated.action` | string | Rule action. Allowed values: `allow`, `reject`, `drop`. | | `data.updated.protocol` | string | Network protocol. Allowed values: `tcp`, `udp`, `icmp4`. | | `data.updated.description` | string | Rule description. | | `data.updated.destination_port` | string | Destination port, range, or comma-separated list. | | `data.updated.destination` | string | Destination IPv4 address or CIDR range. | | `data.updated.source_port` | string | Source port, range, or comma-separated list. | | `data.updated.state` | string | Rule state. Allowed values: `enabled`, `disabled`. Default: `"enabled"`. | | `data.updated.icmp_type` | string | ICMP type number. | | `data.updated.icmp_code` | string | ICMP code number. | Media type: application/json ```json { "statusCode": 200, "message": "Egress rule state toggled successfully", "data": { "direction": "egress", "new_state": "enabled", "updated": { "action": "allow", "protocol": "tcp", "description": "Allow outbound HTTPS", "destination_port": "443", "destination": "0.0.0.0/0", "state": "enabled" } } } ``` Media type: application/json The body contains `statusCode`, `error`, and `message`. ```json { "statusCode": 401, "error": "MISSING_TOKEN", "message": "Authorization header is required" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `MISSING_TOKEN` | Authentication token missing | The request carries no Authorization header, or the header holds no token. | Send an Authorization header as `Bearer ` with a sign-in token or an auth token. | | `INVALID_TOKEN` | Invalid authentication token | The provided authentication token is malformed or invalid. | Obtain a new token by logging in again or using a valid auth token. | | `TOKEN_EXPIRED` | Authentication token expired | The sign-in token (JWT) has expired. An expired auth token is refused with `INVALID_TOKEN` instead. | Sign in again, or refresh the session. | | `AUTH_TOKEN_LINEAGE_REVOKED` | Parent auth token no longer valid | The auth token was created by another auth token, and that token, or one above it, has been revoked, disabled, or has expired, so this token no longer authenticates. | Create a new auth token from a valid one, or sign in again. | | `INVALID_CREDENTIALS` | Invalid credentials | The provided username or email address, or password, is incorrect. | Verify your credentials and try again, or use the password reset feature. | | `EMAIL_NOT_VERIFIED` | Email not verified | The password is correct, but the account's email address is not verified yet. HTTP Basic authentication can return this error on any operation without the email. | Complete email verification, request another verification link, or complete a password reset. | | `INVALID_OTP_CODE` | Invalid OTP code | The provided 2FA code is incorrect or has expired. | Generate a new code from your authenticator app and try again. | Media type: application/json The body contains `statusCode`, `error`, and `message`. ```json { "statusCode": 403, "error": "INSUFFICIENT_PERMISSIONS", "message": "Insufficient permissions" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `computer_quarantined` | Computer is quarantined | The computer is held for review, so its firewall cannot change, including for an admin. Nothing was changed. | Contact support. | | `INSUFFICIENT_PERMISSIONS` | Insufficient permissions | You do not have the required permissions to perform this action. | Ask the resource owner to grant you access. | | `ACCOUNT_BANNED` | Account banned | Your account has been banned and cannot access this resource. | Contact support for information about your account status. | Media type: application/json The computer or its project does not exist. A computer you do not have access to is refused with `403`. The body contains `statusCode`, `error`, and `message`. ```json { "statusCode": 404, "error": "Not Found", "message": "Computer not found" } ``` Media type: application/json The body contains `statusCode`, `error`, `message`, and `data`. ```json { "statusCode": 409, "error": "computer_finalizing", "message": "This computer is still being set up. Retry in a few seconds." } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `computer_finalizing` | Computer is still being set up | The computer is still being set up and refuses changes until that completes. | Retry in a few seconds. | | `COMPUTER_EXPIRED` | Computer has expired | The computer expired when its server ended or was reinstalled, so its firewall cannot change. Nothing was changed. | The computer cannot be changed again. Delete it, then create a new computer. | | `OPERATION_STATE_CONFLICT` | Computer state does not allow firewall changes | The computer is being created or deleted, or was deleted, so its firewall cannot change. The message names the status. Nothing was changed. | Retry once the computer has been created. A deleted computer cannot be changed. | | `SUBSERVER_DORMANT` | Subserver is not active | The computer is on a paid subserver whose subscription is not active, or a change to it is in progress, so its firewall cannot change. `data.reason` is `not_active`, `operation_in_flight`, or `no_subscription`. Nothing was changed. | Retry once the subserver is active again. | Media type: application/json The body contains `statusCode`, `error`, `message`, and `data`. For a schema failure, each `data` entry contains `instancePath`, `schemaPath`, `keyword`, `params`, and `message`. ```json { "statusCode": 422, "error": "Validation Error", "message": "Validation failed: /state must be string", "data": [ { "instancePath": "/state", "schemaPath": "#/properties/state/type", "keyword": "type", "params": { "type": "string" }, "message": "must be string" } ] } ``` Media type: application/json The body contains `statusCode`, `error`, and `message`. ```json { "statusCode": 429, "error": "Too Many Requests", "message": "Rate limit exceeded for this endpoint. Please try again later." } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `RATE_LIMIT_EXCEEDED` | Rate limit exceeded | Too many requests of this kind in a short time, counted per account, auth token, or address. The request was not carried out. | Wait the number of seconds in the `Retry-After` header, then try again. | The `Retry-After` header contains the number of seconds to wait before retrying. Media type: application/json The firewall change failed unexpectedly. It may or may not have been applied. The body contains `statusCode`, `error`, `message`, and `data`, where `data` is any JSON value. ```json { "statusCode": 500, "error": "Internal Server Error", "message": "Failed to toggle egress firewall rule" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `INTERNAL_SERVER_ERROR` | Internal server error | The firewall change failed unexpectedly. It may or may not have been applied. | List the rules to see the current state, then retry if needed. If the problem persists, contact support. | Media type: application/json The firewall could not be reached for a moment. Nothing was changed. Retry after the `Retry-After` header. The body contains `statusCode`, `error`, `message`, and `data`. ```json { "statusCode": 503, "error": "FIREWALL_HOST_UNAVAILABLE", "message": "This computer's firewall rules could not be changed right now. No changes were made. Retry shortly.", "data": { "field": "firewall", "computer_id": "507f1f77bcf86cd799439011" } } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `FIREWALL_HOST_UNAVAILABLE` | Firewall temporarily unavailable | The computer's firewall could not be reached for a moment, for example because its server is busy. Nothing was changed. | Retry after the number of seconds in the `Retry-After` header. | ### Usage ```bash curl --request PATCH \ --url 'https://api.hoody.com/api/v1/computers/{id}/firewall/egress' \ --header "Authorization: Bearer $HOODY_TOKEN" \ --header "Content-Type: application/json" \ --data '{ "state": "enabled", "action": "drop", "protocol": "tcp", "destination_port": "25", "destination": "0.0.0.0/0" }' ``` ```typescript import { HoodyClient } from 'hoody-sdk'; const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN }); const response = await client.api.firewall.egress.enable("c_abc123def456", { action: "drop", protocol: "tcp", destination_port: "25", destination: "0.0.0.0/0", }); console.log(response); ``` The SDK state methods are: - `client.api.firewall.egress.enable(id, data)` sets `state: "enabled"`. - `client.api.firewall.egress.disable(id, data)` sets `state: "disabled"`. ## `DELETE /api/v1/computers/{id}/firewall/ingress` Removes one or more ingress rules. Supply filters that identify the rules to remove, or set `all: true` to remove all ingress rules. If `state` is omitted, rules in either state match. Removal filters do not require `destination_port` when `protocol` is `tcp` or `udp`. This operation does not reset the firewall. ### Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `id` | path | string | Yes | Computer ID. | ### Request body The request body is required. Each field is optional, but the request must contain at least one filter or set `all: true`. | Name | Type | Required | Description | |---|---|---|---| | `all` | boolean | No | Remove all matching rules. By default, only the first match is removed. Set to `true` with no other filters to remove all ingress rules. | | `action` | string | No | Match rules with this action. Allowed values: `allow`, `reject`, `drop`. | | `protocol` | string | No | Match rules with this protocol. Allowed values: `tcp`, `udp`, `icmp4`. | | `destination_port` | string | No | Match this destination port, range, or comma-separated list. It is not required for removal filters that use `tcp` or `udp`. Maximum length: 64 characters. | | `source` | string | No | Match this source IPv4 address or CIDR range. Maximum length: 512 characters. | | `source_port` | string | No | Match this source port, range, or comma-separated list. Maximum length: 64 characters. | | `description` | string | No | Match this rule description. Maximum length: 255 characters. | | `state` | string | No | Match only rules in this state. Allowed values: `enabled`, `disabled`. Omit to match rules in either state. | | `icmp_type` | string | No | Match this ICMP type number. Maximum length: 8 characters. | | `icmp_code` | string | No | Match this ICMP code number. Maximum length: 8 characters. | ### Responses #### Successful response fields | Field | Type | Description | |---|---|---| | `statusCode` | number | HTTP status code. | | `message` | string | Result message. | | `data.direction` | string | Direction of the removed rules. | | `data.removed_count` | number | Number of removed rules. | | `data.removed[]` | array | Removed ingress rules. | | `data.removed[].action` | string | Rule action. Allowed values: `allow`, `reject`, `drop`. | | `data.removed[].protocol` | string | Network protocol. Allowed values: `tcp`, `udp`, `icmp4`. | | `data.removed[].description` | string | Rule description. | | `data.removed[].destination_port` | string | Destination port, range, or comma-separated list. | | `data.removed[].source` | string | Source IPv4 address or CIDR range. | | `data.removed[].source_port` | string | Source port, range, or comma-separated list. | | `data.removed[].state` | string | Rule state. Allowed values: `enabled`, `disabled`. Default: `"enabled"`. | | `data.removed[].icmp_type` | string | ICMP type number. | | `data.removed[].icmp_code` | string | ICMP code number. | Media type: application/json ```json { "statusCode": 200, "message": "Ingress rule(s) removed successfully", "data": { "direction": "ingress", "removed_count": 1, "removed": [ { "action": "allow", "protocol": "tcp", "description": "Allow SSH from office", "destination_port": "22", "source": "192.168.1.0/24", "state": "enabled" } ] } } ``` Media type: application/json The body contains `statusCode`, `error`, `message`, and `data`. ```json { "statusCode": 400, "error": "FIREWALL_UNKNOWN_FILTER", "message": "Unrecognised firewall filter(s)." } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `FIREWALL_UNKNOWN_FILTER` | Unrecognised Firewall Filter | A remove request carried a filter this direction does not have, such as a misspelled name or a field that belongs to the other direction. `destination` belongs to egress and `source` belongs to ingress. An unrecognised filter would be ignored, which combined with `all: true` would remove every rule in the direction. `data.unknown_filters` lists the names. Nothing was removed. | Correct or drop the names listed in `data.unknown_filters` and send the request again. | | `INVALID_RULE_DEFINITION` | Invalid Firewall Rule | A filter value is malformed: a port outside 1-65535, a range whose first port is not lower, ports with a protocol other than `tcp` or `udp`, or an address that is not IPv4 or IPv4 CIDR. `data.field` names the field. Nothing was removed. | Correct the field named in `data.field`. Ports are 1-65535, ranges are written low-high, and addresses are comma-separated IPv4 addresses or CIDR ranges. | Media type: application/json The body contains `statusCode`, `error`, and `message`. ```json { "statusCode": 401, "error": "MISSING_TOKEN", "message": "Authorization header is required" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `MISSING_TOKEN` | Authentication token missing | The request carries no Authorization header, or the header holds no token. | Send an Authorization header as `Bearer ` with a sign-in token or an auth token. | | `INVALID_TOKEN` | Invalid authentication token | The provided authentication token is malformed or invalid. | Obtain a new token by logging in again or using a valid auth token. | | `TOKEN_EXPIRED` | Authentication token expired | The sign-in token (JWT) has expired. An expired auth token is refused with `INVALID_TOKEN` instead. | Sign in again, or refresh the session. | | `AUTH_TOKEN_LINEAGE_REVOKED` | Parent auth token no longer valid | The auth token was created by another auth token, and that token, or one above it, has been revoked, disabled, or has expired, so this token no longer authenticates. | Create a new auth token from a valid one, or sign in again. | | `INVALID_CREDENTIALS` | Invalid credentials | The provided username or email address, or password, is incorrect. | Verify your credentials and try again, or use the password reset feature. | | `EMAIL_NOT_VERIFIED` | Email not verified | The password is correct, but the account's email address is not verified yet. HTTP Basic authentication can return this error on any operation without the email. | Complete email verification, request another verification link, or complete a password reset. | | `INVALID_OTP_CODE` | Invalid OTP code | The provided 2FA code is incorrect or has expired. | Generate a new code from your authenticator app and try again. | Media type: application/json The body contains `statusCode`, `error`, and `message`. ```json { "statusCode": 403, "error": "INSUFFICIENT_PERMISSIONS", "message": "Insufficient permissions" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `computer_quarantined` | Computer is quarantined | The computer is held for review, so its firewall cannot change, including for an admin. Nothing was changed. | Contact support. | | `INSUFFICIENT_PERMISSIONS` | Insufficient permissions | You do not have the required permissions to perform this action. | Ask the resource owner to grant you access. | | `ACCOUNT_BANNED` | Account banned | Your account has been banned and cannot access this resource. | Contact support for information about your account status. | Media type: application/json The computer or its project does not exist. A computer you do not have access to is refused with `403`. The body contains `statusCode`, `error`, and `message`. ```json { "statusCode": 404, "error": "Not Found", "message": "Computer not found" } ``` Media type: application/json The body contains `statusCode`, `error`, `message`, and `data`. ```json { "statusCode": 409, "error": "computer_finalizing", "message": "This computer is still being set up. Retry in a few seconds." } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `computer_finalizing` | Computer is still being set up | The computer is still being set up and refuses changes until that completes. | Retry in a few seconds. | | `COMPUTER_EXPIRED` | Computer has expired | The computer expired when its server ended or was reinstalled, so its firewall cannot change. Nothing was changed. | The computer cannot be changed again. Delete it, then create a new computer. | | `OPERATION_STATE_CONFLICT` | Computer state does not allow firewall changes | The computer is being created or deleted, or was deleted, so its firewall cannot change. The message names the status. Nothing was changed. | Retry once the computer has been created. A deleted computer cannot be changed. | | `SUBSERVER_DORMANT` | Subserver is not active | The computer is on a paid subserver whose subscription is not active, or a change to it is in progress, so its firewall cannot change. `data.reason` is `not_active`, `operation_in_flight`, or `no_subscription`. Nothing was changed. | Retry once the subserver is active again. | Media type: application/json The body contains `statusCode`, `error`, `message`, and `data`. ```json { "statusCode": 422, "error": "FIREWALL_FILTER_REQUIRED", "message": "Give at least one filter (for example protocol and destination_port) to choose the rule to remove, or set \"all\": true to remove every rule in this direction.", "data": { "field": "firewall_filter" } } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `FIREWALL_FILTER_REQUIRED` | Firewall rule filter required | A remove request named no rule: it carried no filter with a value and did not set `all: true`. Nothing was removed. | Send at least one filter, such as `protocol` and `destination_port`, or `all: true` to remove every rule in the direction. | Media type: application/json The body contains `statusCode`, `error`, and `message`. ```json { "statusCode": 429, "error": "Too Many Requests", "message": "Rate limit exceeded for this endpoint. Please try again later." } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `RATE_LIMIT_EXCEEDED` | Rate limit exceeded | Too many requests of this kind in a short time, counted per account, auth token, or address. The request was not carried out. | Wait the number of seconds in the `Retry-After` header, then try again. | The `Retry-After` header contains the number of seconds to wait before retrying. Media type: application/json The firewall change failed unexpectedly. It may or may not have been applied. The body contains `statusCode`, `error`, `message`, and `data`, where `data` is any JSON value. ```json { "statusCode": 500, "error": "Internal Server Error", "message": "Failed to remove ingress firewall rule" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `INTERNAL_SERVER_ERROR` | Internal server error | The firewall change failed unexpectedly. It may or may not have been applied. | List the rules to see the current state, then retry if needed. If the problem persists, contact support. | Media type: application/json The firewall could not be reached for a moment. Nothing was changed. Retry after the `Retry-After` header. The body contains `statusCode`, `error`, `message`, and `data`. ```json { "statusCode": 503, "error": "FIREWALL_HOST_UNAVAILABLE", "message": "This computer's firewall rules could not be changed right now. No changes were made. Retry shortly.", "data": { "field": "firewall", "computer_id": "507f1f77bcf86cd799439011" } } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `FIREWALL_HOST_UNAVAILABLE` | Firewall temporarily unavailable | The computer's firewall could not be reached for a moment, for example because its server is busy. Nothing was changed. | Retry after the number of seconds in the `Retry-After` header. | ### Usage ```bash curl --request DELETE \ --url 'https://api.hoody.com/api/v1/computers/{id}/firewall/ingress' \ --header "Authorization: Bearer $HOODY_TOKEN" \ --header "Content-Type: application/json" \ --data '{ "protocol": "tcp", "destination_port": "22", "source": "203.0.113.5/32" }' ``` ```typescript import { HoodyClient } from 'hoody-sdk'; const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN }); const response = await client.api.firewall.ingress.delete("c_abc123def456", { protocol: "tcp", destination_port: "22", source: "203.0.113.5/32", }); console.log(response); ``` ## `DELETE /api/v1/computers/{id}/firewall/egress` Removes one or more egress rules. Supply filters that identify the rules to remove, or set `all: true` to remove all egress rules. If `state` is omitted, rules in either state match. Removal filters do not require `destination_port` when `protocol` is `tcp` or `udp`. This operation does not reset the firewall. ### Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `id` | path | string | Yes | Computer ID. | ### Request body The request body is required. Each field is optional, but the request must contain at least one filter or set `all: true`. | Name | Type | Required | Description | |---|---|---|---| | `all` | boolean | No | Remove all matching rules. By default, only the first match is removed. Set to `true` with no other filters to remove all egress rules. | | `action` | string | No | Match rules with this action. Allowed values: `allow`, `reject`, `drop`. | | `protocol` | string | No | Match rules with this protocol. Allowed values: `tcp`, `udp`, `icmp4`. | | `destination_port` | string | No | Match this destination port, range, or comma-separated list. It is not required for removal filters that use `tcp` or `udp`. Maximum length: 64 characters. | | `destination` | string | No | Match this destination IPv4 address or CIDR range. Maximum length: 512 characters. | | `source_port` | string | No | Match this source port, range, or comma-separated list. Maximum length: 64 characters. | | `description` | string | No | Match this rule description. Maximum length: 255 characters. | | `state` | string | No | Match only rules in this state. Allowed values: `enabled`, `disabled`. Omit to match rules in either state. | | `icmp_type` | string | No | Match this ICMP type number. Maximum length: 8 characters. | | `icmp_code` | string | No | Match this ICMP code number. Maximum length: 8 characters. | ### Responses #### Successful response fields | Field | Type | Description | |---|---|---| | `statusCode` | number | HTTP status code. | | `message` | string | Result message. | | `data.direction` | string | Direction of the removed rules. | | `data.removed_count` | number | Number of removed rules. | | `data.removed[]` | array | Removed egress rules. | | `data.removed[].action` | string | Rule action. Allowed values: `allow`, `reject`, `drop`. | | `data.removed[].protocol` | string | Network protocol. Allowed values: `tcp`, `udp`, `icmp4`. | | `data.removed[].description` | string | Rule description. | | `data.removed[].destination_port` | string | Destination port, range, or comma-separated list. | | `data.removed[].destination` | string | Destination IPv4 address or CIDR range. | | `data.removed[].source_port` | string | Source port, range, or comma-separated list. | | `data.removed[].state` | string | Rule state. Allowed values: `enabled`, `disabled`. Default: `"enabled"`. | | `data.removed[].icmp_type` | string | ICMP type number. | | `data.removed[].icmp_code` | string | ICMP code number. | Media type: application/json ```json { "statusCode": 200, "message": "Egress rule(s) removed successfully", "data": { "direction": "egress", "removed_count": 2, "removed": [ { "action": "allow", "protocol": "tcp", "description": "Allow outbound HTTPS", "destination_port": "443", "destination": "0.0.0.0/0", "state": "enabled" }, { "action": "allow", "protocol": "tcp", "description": "Allow outbound DNS", "destination_port": "53", "destination": "8.8.8.8", "state": "enabled" } ] } } ``` Media type: application/json The body contains `statusCode`, `error`, `message`, and `data`. ```json { "statusCode": 400, "error": "FIREWALL_UNKNOWN_FILTER", "message": "Unrecognised firewall filter(s)." } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `FIREWALL_UNKNOWN_FILTER` | Unrecognised Firewall Filter | A remove request carried a filter this direction does not have, such as a misspelled name or a field that belongs to the other direction. `destination` belongs to egress and `source` belongs to ingress. An unrecognised filter would be ignored, which combined with `all: true` would remove every rule in the direction. `data.unknown_filters` lists the names. Nothing was removed. | Correct or drop the names listed in `data.unknown_filters` and send the request again. | | `INVALID_RULE_DEFINITION` | Invalid Firewall Rule | A filter value is malformed: a port outside 1-65535, a range whose first port is not lower, ports with a protocol other than `tcp` or `udp`, or an address that is not IPv4 or IPv4 CIDR. `data.field` names the field. Nothing was removed. | Correct the field named in `data.field`. Ports are 1-65535, ranges are written low-high, and addresses are comma-separated IPv4 addresses or CIDR ranges. | Media type: application/json The body contains `statusCode`, `error`, and `message`. ```json { "statusCode": 401, "error": "MISSING_TOKEN", "message": "Authorization header is required" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `MISSING_TOKEN` | Authentication token missing | The request carries no Authorization header, or the header holds no token. | Send an Authorization header as `Bearer ` with a sign-in token or an auth token. | | `INVALID_TOKEN` | Invalid authentication token | The provided authentication token is malformed or invalid. | Obtain a new token by logging in again or using a valid auth token. | | `TOKEN_EXPIRED` | Authentication token expired | The sign-in token (JWT) has expired. An expired auth token is refused with `INVALID_TOKEN` instead. | Sign in again, or refresh the session. | | `AUTH_TOKEN_LINEAGE_REVOKED` | Parent auth token no longer valid | The auth token was created by another auth token, and that token, or one above it, has been revoked, disabled, or has expired, so this token no longer authenticates. | Create a new auth token from a valid one, or sign in again. | | `INVALID_CREDENTIALS` | Invalid credentials | The provided username or email address, or password, is incorrect. | Verify your credentials and try again, or use the password reset feature. | | `EMAIL_NOT_VERIFIED` | Email not verified | The password is correct, but the account's email address is not verified yet. HTTP Basic authentication can return this error on any operation without the email. | Complete email verification, request another verification link, or complete a password reset. | | `INVALID_OTP_CODE` | Invalid OTP code | The provided 2FA code is incorrect or has expired. | Generate a new code from your authenticator app and try again. | Media type: application/json The body contains `statusCode`, `error`, and `message`. ```json { "statusCode": 403, "error": "INSUFFICIENT_PERMISSIONS", "message": "Insufficient permissions" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `computer_quarantined` | Computer is quarantined | The computer is held for review, so its firewall cannot change, including for an admin. Nothing was changed. | Contact support. | | `INSUFFICIENT_PERMISSIONS` | Insufficient permissions | You do not have the required permissions to perform this action. | Ask the resource owner to grant you access. | | `ACCOUNT_BANNED` | Account banned | Your account has been banned and cannot access this resource. | Contact support for information about your account status. | Media type: application/json The computer or its project does not exist. A computer you do not have access to is refused with `403`. The body contains `statusCode`, `error`, and `message`. ```json { "statusCode": 404, "error": "Not Found", "message": "Computer not found" } ``` Media type: application/json The body contains `statusCode`, `error`, `message`, and `data`. ```json { "statusCode": 409, "error": "computer_finalizing", "message": "This computer is still being set up. Retry in a few seconds." } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `computer_finalizing` | Computer is still being set up | The computer is still being set up and refuses changes until that completes. | Retry in a few seconds. | | `COMPUTER_EXPIRED` | Computer has expired | The computer expired when its server ended or was reinstalled, so its firewall cannot change. Nothing was changed. | The computer cannot be changed again. Delete it, then create a new computer. | | `OPERATION_STATE_CONFLICT` | Computer state does not allow firewall changes | The computer is being created or deleted, or was deleted, so its firewall cannot change. The message names the status. Nothing was changed. | Retry once the computer has been created. A deleted computer cannot be changed. | | `SUBSERVER_DORMANT` | Subserver is not active | The computer is on a paid subserver whose subscription is not active, or a change to it is in progress, so its firewall cannot change. `data.reason` is `not_active`, `operation_in_flight`, or `no_subscription`. Nothing was changed. | Retry once the subserver is active again. | Media type: application/json The body contains `statusCode`, `error`, `message`, and `data`. ```json { "statusCode": 422, "error": "FIREWALL_FILTER_REQUIRED", "message": "Give at least one filter (for example protocol and destination_port) to choose the rule to remove, or set \"all\": true to remove every rule in this direction.", "data": { "field": "firewall_filter" } } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `FIREWALL_FILTER_REQUIRED` | Firewall rule filter required | A remove request named no rule: it carried no filter with a value and did not set `all: true`. Nothing was removed. | Send at least one filter, such as `protocol` and `destination_port`, or `all: true` to remove every rule in the direction. | Media type: application/json The body contains `statusCode`, `error`, and `message`. ```json { "statusCode": 429, "error": "Too Many Requests", "message": "Rate limit exceeded for this endpoint. Please try again later." } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `RATE_LIMIT_EXCEEDED` | Rate limit exceeded | Too many requests of this kind in a short time, counted per account, auth token, or address. The request was not carried out. | Wait the number of seconds in the `Retry-After` header, then try again. | The `Retry-After` header contains the number of seconds to wait before retrying. Media type: application/json The firewall change failed unexpectedly. It may or may not have been applied. The body contains `statusCode`, `error`, `message`, and `data`, where `data` is any JSON value. ```json { "statusCode": 500, "error": "Internal Server Error", "message": "Failed to remove egress firewall rule" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `INTERNAL_SERVER_ERROR` | Internal server error | The firewall change failed unexpectedly. It may or may not have been applied. | List the rules to see the current state, then retry if needed. If the problem persists, contact support. | Media type: application/json The firewall could not be reached for a moment. Nothing was changed. Retry after the `Retry-After` header. The body contains `statusCode`, `error`, `message`, and `data`. ```json { "statusCode": 503, "error": "FIREWALL_HOST_UNAVAILABLE", "message": "This computer's firewall rules could not be changed right now. No changes were made. Retry shortly.", "data": { "field": "firewall", "computer_id": "507f1f77bcf86cd799439011" } } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `FIREWALL_HOST_UNAVAILABLE` | Firewall temporarily unavailable | The computer's firewall could not be reached for a moment, for example because its server is busy. Nothing was changed. | Retry after the number of seconds in the `Retry-After` header. | ### Usage ```bash curl --request DELETE \ --url 'https://api.hoody.com/api/v1/computers/{id}/firewall/egress' \ --header "Authorization: Bearer $HOODY_TOKEN" \ --header "Content-Type: application/json" \ --data '{ "protocol": "tcp", "destination_port": "25" }' ``` ```typescript import { HoodyClient } from 'hoody-sdk'; const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN }); const response = await client.api.firewall.egress.delete("c_abc123def456", { protocol: "tcp", destination_port: "25", }); console.log(response); ``` ## `POST /api/v1/computers/{id}/firewall/reset` Removes all firewall rules and returns the computer to an open state. ### Parameters | Name | In | Type | Required | Description | |---|---|---|---|---| | `id` | path | string | Yes | Computer ID. | ### Request This endpoint does not accept a request body. ### Responses #### Successful response fields | Field | Type | Description | |---|---|---| | `statusCode` | number | HTTP status code. | | `message` | string | Result message. | | `data` | object | Reset result. | | `data.rules` | object | Rules remaining after the reset. | | `data.rules.ingress` | array | Remaining ingress rules. | | `data.rules.egress` | array | Remaining egress rules. | Media type: application/json ```json { "statusCode": 200, "message": "Firewall reset successfully", "data": { "rules": { "ingress": [], "egress": [] } } } ``` Media type: application/json The body contains `statusCode`, `error`, and `message`. ```json { "statusCode": 401, "error": "MISSING_TOKEN", "message": "Authorization header is required" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `MISSING_TOKEN` | Authentication token missing | The request carries no Authorization header, or the header holds no token. | Send an Authorization header as `Bearer ` with a sign-in token or an auth token. | | `INVALID_TOKEN` | Invalid authentication token | The provided authentication token is malformed or invalid. | Obtain a new token by logging in again or using a valid auth token. | | `TOKEN_EXPIRED` | Authentication token expired | The sign-in token (JWT) has expired. An expired auth token is refused with `INVALID_TOKEN` instead. | Sign in again, or refresh the session. | | `AUTH_TOKEN_LINEAGE_REVOKED` | Parent auth token no longer valid | The auth token was created by another auth token, and that token, or one above it, has been revoked, disabled, or has expired, so this token no longer authenticates. | Create a new auth token from a valid one, or sign in again. | | `INVALID_CREDENTIALS` | Invalid credentials | The provided username or email address, or password, is incorrect. | Verify your credentials and try again, or use the password reset feature. | | `EMAIL_NOT_VERIFIED` | Email not verified | The password is correct, but the account's email address is not verified yet. HTTP Basic authentication can return this error on any operation without the email. | Complete email verification, request another verification link, or complete a password reset. | | `INVALID_OTP_CODE` | Invalid OTP code | The provided 2FA code is incorrect or has expired. | Generate a new code from your authenticator app and try again. | Media type: application/json The body contains `statusCode`, `error`, and `message`. ```json { "statusCode": 403, "error": "INSUFFICIENT_PERMISSIONS", "message": "Insufficient permissions" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `computer_quarantined` | Computer is quarantined | The computer is held for review, so its firewall cannot change, including for an admin. Nothing was changed. | Contact support. | | `INSUFFICIENT_PERMISSIONS` | Insufficient permissions | You do not have the required permissions to perform this action. | Ask the resource owner to grant you access. | | `ACCOUNT_BANNED` | Account banned | Your account has been banned and cannot access this resource. | Contact support for information about your account status. | Media type: application/json The computer or its project does not exist. A computer you do not have access to is refused with `403`. The body contains `statusCode`, `error`, and `message`. ```json { "statusCode": 404, "error": "Not Found", "message": "Computer not found" } ``` Media type: application/json The body contains `statusCode`, `error`, `message`, and `data`. ```json { "statusCode": 409, "error": "computer_finalizing", "message": "This computer is still being set up. Retry in a few seconds." } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `computer_finalizing` | Computer is still being set up | The computer is still being set up and refuses changes until that completes. | Retry in a few seconds. | | `COMPUTER_EXPIRED` | Computer has expired | The computer expired when its server ended or was reinstalled, so its firewall cannot change. Nothing was changed. | The computer cannot be changed again. Delete it, then create a new computer. | | `OPERATION_STATE_CONFLICT` | Computer state does not allow firewall changes | The computer is being created or deleted, or was deleted, so its firewall cannot change. The message names the status. Nothing was changed. | Retry once the computer has been created. A deleted computer cannot be changed. | | `SUBSERVER_DORMANT` | Subserver is not active | The computer is on a paid subserver whose subscription is not active, or a change to it is in progress, so its firewall cannot change. `data.reason` is `not_active`, `operation_in_flight`, or `no_subscription`. Nothing was changed. | Retry once the subserver is active again. | Media type: application/json The body contains `statusCode`, `error`, `message`, and `data`. For a schema failure, each `data` entry contains `instancePath`, `schemaPath`, `keyword`, `params`, and `message`. ```json { "statusCode": 422, "error": "Validation Error", "message": "Validation failed: /id must be string", "data": [ { "instancePath": "/id", "schemaPath": "#/properties/id/type", "keyword": "type", "params": { "type": "string" }, "message": "must be string" } ] } ``` Media type: application/json The body contains `statusCode`, `error`, and `message`. ```json { "statusCode": 429, "error": "Too Many Requests", "message": "Rate limit exceeded for this endpoint. Please try again later." } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `RATE_LIMIT_EXCEEDED` | Rate limit exceeded | Too many requests of this kind in a short time, counted per account, auth token, or address. The request was not carried out. | Wait the number of seconds in the `Retry-After` header, then try again. | The `Retry-After` header contains the number of seconds to wait before retrying. Media type: application/json The firewall change failed unexpectedly. It may or may not have been applied. The body contains `statusCode`, `error`, `message`, and `data`, where `data` is any JSON value. ```json { "statusCode": 500, "error": "Internal Server Error", "message": "Failed to reset firewall" } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `INTERNAL_SERVER_ERROR` | Internal server error | The firewall change failed unexpectedly. It may or may not have been applied. | List the rules to see the current state, then retry if needed. If the problem persists, contact support. | Media type: application/json The firewall could not be reached for a moment. Nothing was changed. Retry after the `Retry-After` header. The body contains `statusCode`, `error`, `message`, and `data`. ```json { "statusCode": 503, "error": "FIREWALL_HOST_UNAVAILABLE", "message": "This computer's firewall rules could not be changed right now. No changes were made. Retry shortly.", "data": { "field": "firewall", "computer_id": "507f1f77bcf86cd799439011" } } ``` | Error Code | Title | Description | Resolution | |---|---|---|---| | `FIREWALL_HOST_UNAVAILABLE` | Firewall temporarily unavailable | The computer's firewall could not be reached for a moment, for example because its server is busy. Nothing was changed. | Retry after the number of seconds in the `Retry-After` header. | ### Usage ```bash curl --request POST \ --url 'https://api.hoody.com/api/v1/computers/{id}/firewall/reset' \ --header "Authorization: Bearer $HOODY_TOKEN" ``` ```typescript import { HoodyClient } from 'hoody-sdk'; const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: process.env.HOODY_TOKEN }); const response = await client.api.firewall.reset("c_abc123def456"); console.log(response); ```