# Support reference **Page:** foundation/support/reference [Download Raw Markdown](./foundation/support/reference.md) --- # Support reference Lookup tables for [support](/foundation/support/). Every parameter and response field is in the [Support tickets API reference](/api/users/#support). ## Calls All nine operations are in the CLI (`hoody support`) and the SDK (`client.api.support`). Every answer, refusals included, carries `Cache-Control: no-store`. | What it does | Method and path | CLI | SDK | |---|---|---|---| | Open a ticket with its first message | `POST /api/v1/support/tickets` | `hoody support create` | `tickets.create` | | List your tickets, most recent message first | `GET /api/v1/support/tickets` | `hoody support list` | `tickets.list` | | Tickets changed since your last poll | `GET /api/v1/support/tickets/changes` | `hoody support changes list` | `tickets.listChanges` | | One ticket with its messages (marks it read) | `GET /api/v1/support/tickets/{id}` | `hoody support get` | `tickets.get` | | Add a message to a ticket | `POST /api/v1/support/tickets/{id}/messages` | `hoody support reply` | `tickets.reply` | | Close a ticket (no request body); the CLI asks for confirmation | `POST /api/v1/support/tickets/{id}/close` | `hoody support close` | `tickets.close` | | Find the ticket a create with this `client_key` made | `GET /api/v1/support/tickets/by-key` | `hoody support keys get` | `tickets.getByKey` | | Find the reply a `client_key` added to a ticket | `GET /api/v1/support/tickets/{id}/messages/by-key` | `hoody support messages keys get` | `tickets.getMessageByKey` | | Your limits and what is used now | `GET /api/v1/support/limits` | `hoody support limits get` | `getLimits` | ## Access Who can use support is on the [guide](/foundation/support/#who-can-use-support). Refusals: | Caller | Result | |---|---| | Auth token without `resources.support`, or limited to realms | 403 | | HTTP Basic credentials, an impersonated session, a realm host | 403 `INSUFFICIENT_PERMISSIONS` | | Admin or platform account | 403 `SUPPORT_NOT_FOR_ACCOUNT` | | Staff account | Refused earlier: 403 `STAFF_ACCOUNT_SCOPE` with a signed-in session, 401 `STAFF_JWT_REQUIRED` with an auth token | ## Accepted text | Item | Rule | |---|---| | Subject | One line of up to 200 characters | | Message | Up to 4,000 characters, 200 lines and 16,000 bytes of UTF-8, with no single line longer than 2,000 characters | | Format | Plain text: nothing is rendered as HTML or Markdown, and there are no attachments or images | | Far over the size | A subject over 2,000 characters or a message over 16,000 characters as sent is refused before the text check, with 400 `SUPPORT_FIELD_INVALID` | Harmless noise is cleaned before the text is stored, and each rule that changed something is listed in `cleaned`. A field that was stored exactly as sent is absent from `cleaned`. | Rule | What it does | |---|---| | `C1` | Turns every line-ending form into a single line feed | | `C2` | Applies Unicode NFC normalisation | | `C3` | Removes spaces and tabs at the end of each line | | `C4` | Trims the subject; removes blank lines at the start and end of a message | | `C5` | Reduces more than two blank lines in a row to two | | `C6` | Removes invisible copy-paste debris such as zero-width spaces, soft hyphens and byte order marks | | `C7` | Removes joiners and variation selectors outside the places a script or an emoji needs them | The create answers 201 with the ticket, its first message and `cleaned`: ```json { "statusCode": 201, "message": "Support ticket created", "data": { "ticket": { "id": "6720a1b2c3d4e5f6a7b8c9d0", "subject": "Computer will not start after resize", "category": "computers", "status": "open", "terminal": false, "unread": false, "created_at": "2026-10-28T09:15:00.000Z", "last_message_at": "2026-10-28T09:15:00.000Z", "closed_at": null, "reopenable": false }, "message": { "id": "6720a1b2c3d4e5f6a7b8c9d1", "seq": 1, "from": "you", "body": "Since resizing to 4 GB my computer stays in \"starting\". Started 09:00 UTC.", "created_at": "2026-10-28T09:15:00.000Z" }, "cleaned": {} } } ``` Characters that hide or reorder text are refused rather than removed. A refusal is 400 `SUPPORT_TEXT_INVALID`, and the error never repeats your text: ```json { "statusCode": 400, "error": "SUPPORT_TEXT_INVALID", "message": "body is not accepted as plain text.", "data": { "field": "body", "rule": "too_long", "at": "cleaned", "index": 4000 } } ``` | `data` field | Meaning | |---|---| | `field` | `subject` or `body` | | `rule` | The check that failed (below) | | `at` | `input` (the text as sent) or `cleaned` (after cleaning) | | `index` | The character offset of the problem | | `rule` | Meaning | |---|---| | `too_long`, `too_many_lines`, `line_too_long` | Over a size limit | | `empty` | Nothing visible is left | | `multiline` | A line break in the subject | | `lone_surrogate`, `nul`, `escape`, `c0_control`, `c1_control` | Control characters | | `bidi_control`, `invisible_char`, `tag_char` | Characters that hide or reorder text | | `private_use`, `noncharacter` | Code points with no public meaning | | `combining_flood` | Too many combining marks on one character | ## Ticket lifecycle Statuses and reopening are on the [guide](/foundation/support/#reply-to-a-ticket-or-close-it). Each ticket also has fixed size limits: | Event | Effect | |---|---| | Reply more than 30 days after closing | 409 `SUPPORT_TICKET_EXPIRED`: open a new ticket | | 50 of your messages on one ticket | You can send at most 50 messages on one ticket; more answer 409 `SUPPORT_TICKET_LIMIT` | | Message 100 of the ticket | A ticket holds at most 100 messages in total. The write that takes message 100 closes the ticket for good: `terminal` becomes `true`, nothing can reopen it, and it stays readable; later replies answer 409 `SUPPORT_TICKET_FULL` | | 198th status change | Closes the ticket for good. Every close, reopen, automatic close and switch between `open` and `waiting_user` counts as one; later replies answer 409 `SUPPORT_TICKET_FULL` | On a ticket closed for good, resending your own latest message within 60 seconds answers 409 `SUPPORT_DUPLICATE` instead; see [Duplicate text](#duplicate-text). ## Tiers and quota | `tier` | When | |---|---| | `paid` | While the account has a server subscription or a server rental that is active or in billing trouble | | `free` | Otherwise | | `banned` | A banned account: the free limits, with one open ticket and two new tickets a day | The limits table on the guide shows the default values; the deployment can change them, and `GET /api/v1/support/limits` always shows the ones in force. Messages from support count against none of your limits, and a reply that reopens a closed ticket also counts against `open`. A reached limit answers 409 `SUPPORT_QUOTA_REACHED`, and nothing is saved: ```json { "statusCode": 409, "error": "SUPPORT_QUOTA_REACHED", "message": "A support limit for this account was reached.", "data": { "limit": "tickets_day", "tier": "free", "retry_after_s": 3600 } } ``` `limit` names the row, `tier` your tier, and `retry_after_s` the seconds until the limit frees itself. `retry_after_s` is present for `tickets_day`, `tickets_30d` and `messages_day`. `open` frees when you close a ticket, and `retained` when old closed tickets are deleted. ## Request limits Request limits apply on top of support limits. A request over one answers 429 `RATE_LIMIT_EXCEEDED` with `Retry-After`. | Limit | Default | |---|---| | Reads per account | 600 a minute | | Writes per account | 120 an hour | | New tickets per address | 60 an hour | | Writes per address | 1,200 an hour | Requests from the public IPv4 address of a Hoody server automatically get higher per-address limits on opening tickets and on writes. Account limits are unchanged. A lookup by `client_key` costs one read against your read limit, uses no ticket or message limit, and never marks a ticket read. Two refusals concern the whole platform rather than your account. In both, nothing was saved, and reading and closing tickets keep working. | Answer | Meaning | |---|---| | 503 `SUPPORT_BUSY` | Support reached its daily volume for all accounts. `Retry-After` gives the seconds to the next UTC midnight | | 503 `SUPPORT_STORAGE_FULL` | Support cannot store new tickets or messages right now | ## Reply notifications | Item | Behaviour | |---|---| | Batching | Several replies on one ticket can share one notification, and you get at most one per ticket every 10 minutes | | `support_reply_email` | On your user record. `GET /api/v1/users/me` shows the value in force (`true` unless you turned it off) | | `support_reply_email_stored` | Whether you made a choice | | Change it | `PUT` or `PATCH /api/v1/users/{id}`, from a signed-in session | ## Change feed and listing | Item | Rule | |---|---| | `next_since` | Opaque and belongs to your account. Store it as it is; never build or edit it, and never use another account's. When nothing of yours changed, the same value comes back | | Browse instead of wait | `GET /api/v1/support/tickets` lists your tickets one page at a time, with an optional `status` filter; pass `next_cursor` back as `cursor` until it is `null` | | Thread paging | Messages newest first, 50 at a time. Reading the latest page also marks the ticket read. When `has_older` is `true`, pass the smallest `seq` you have as `before_seq` to get older messages | ## Safe retries How `client_key` works is on the [guide](/foundation/support/#retry-a-write-safely). | Item | Rule | |---|---| | Scope | Keys of tickets are scoped to your account, and keys of replies to you and one ticket, so use a new key for each new ticket or message | | CLI rerun line | Printed with the key after an unknown outcome. For 503 `SUPPORT_BUSY` and `SUPPORT_STORAGE_FULL` the CLI prints no such line, because nothing was saved | | Ticket lookup | Answers with the ticket and its first message | | Reply lookup | Answers with the message and the ticket, and matches only your own replies on that ticket | | Ticket in a lookup | Comes back as it is now, so its `status` and `unread` can differ from the answer you lost | | `client_key` in the query | Exactly as the write sent it, URL-encoded (`+`, `&`, `#`, `%` and any non-ASCII character) | | Retry after 404 `SUPPORT_KEY_NOT_FOUND` | No saved write carries that key yet. Send the write again with the same body and `client_key`: if the first one was saved and is still kept, the retry returns it with `replayed: true` and creates no copy | ### Duplicate text 409 `SUPPORT_DUPLICATE` means your submission matches text saved less than 60 seconds ago after text cleaning, under another `client_key` or none. It was not saved again and no account limit was spent. The request rate limits still count the request. | Write | Counts as the same when | |---|---| | New ticket | Its subject, category and first message match one of your tickets that is not closed | | Reply | It matches the ticket's latest message, that message is yours, and the ticket is not closed or is closed for good. A support reply in between means the repeated text is a new message | `data` names the saved copy in `ticket_id` and `message_id`, and `retry_after_s` says when the same text stops being refused as a duplicate; another refusal, such as a full ticket, can still apply. Read the saved copy instead of sending it again. To retry a write whose answer was lost, send it with its original `client_key`. ## Privacy and retention Who reads tickets is on the [guide](/foundation/support/#who-reads-my-tickets-and-for-how-long). | Item | Rule | |---|---| | Server logs | Your ticket text is never written to server logs | | Closed tickets | Count toward `retained` until retention deletes them, by default two years after they were closed. Closing a ticket does not delete it | | Never deleted by retention | Open tickets, tickets waiting for you and tickets that can still be reopened | ## Troubleshooting | Symptom, status or message | Cause | What to do | |---|---|---| | 403 | The auth token lacks `resources.support` or is limited to realms, or the request came through a realm host, HTTP Basic or an impersonated session | Add the permission, use an account-wide token, and call `https://api.hoody.com` | | 403 `SUPPORT_NOT_FOR_ACCOUNT` or `STAFF_ACCOUNT_SCOPE`, or 401 `STAFF_JWT_REQUIRED` for a token | A staff, admin or platform account, which cannot use support tickets | Use a member account | | 400 `SUPPORT_FIELD_INVALID` | A field is missing or has the wrong type, or the request has a field the endpoint does not take. `data.field` names the field. An unknown field is reported by its position (`data.position`), never by its name | Compare your keys with the [API reference](/api/users/#support) | | 400 `SUPPORT_TEXT_INVALID` | A text rule failed. `at: "cleaned"` means the problem remains after cleaning, for example a message still over 4,000 characters | Read `data.rule` and `data.index` and fix the text at that offset; [Accepted text](#accepted-text) explains each rule | | 404 `SUPPORT_TICKET_NOT_FOUND` | No ticket with this id belongs to your account. A malformed id answers the same way | Find your ticket ids with `GET /api/v1/support/tickets` | | 404 `SUPPORT_KEY_NOT_FOUND` | The outcome of the write is unknown, not refused | Read again later, or resend the write with the same body and `client_key`, as in [Safe retries](#safe-retries) | | 409 `SUPPORT_QUOTA_REACHED` | A support limit was reached; `data.limit` names it | For `open`, close tickets that are solved; `open` counts tickets waiting for support and tickets waiting for you. For the daily and 30-day rows, wait `data.retry_after_s` seconds | | 409 `SUPPORT_TICKET_LIMIT` | You sent the 50 messages one ticket allows | Open a new ticket; the old one stays readable | | 409 `SUPPORT_TICKET_FULL` | The ticket reached its size limit and is closed for good | Open a new ticket; the old one stays readable | | 409 `SUPPORT_TICKET_EXPIRED` | The ticket was closed more than 30 days ago | Open a new ticket; the old one stays readable | | 409 `SUPPORT_IDEMPOTENCY_CONFLICT` | This `client_key` was already used with a different body | Use a new key for a new ticket or message, or resend the original body exactly to get the first result back | | 409 `SUPPORT_DUPLICATE` | Your submission matches text saved less than 60 seconds ago after text cleaning | Read the saved copy; see [Duplicate text](#duplicate-text) | | 422 `INVALID_CURSOR` | The `since` or `cursor` value is not accepted, for example after a service restore or an API update | For an invalid `since`, call `changes` without `since` and save `next_since`, then list all your tickets, following `next_cursor`, and read each unread ticket. Continue polling from the saved position. For an invalid listing `cursor`, repeat `GET /api/v1/support/tickets` without `cursor`, with the `status` filter you want | | 429 `RATE_LIMIT_EXCEEDED` | Too many requests in a short time | Wait for the seconds in `Retry-After`, and poll no more often than every 60 seconds | | 503 `SUPPORT_BUSY` | Support reached its daily volume; the write was refused without saving anything | Wait for the next UTC midnight, given in `Retry-After` | | 503 `SUPPORT_STORAGE_FULL` | New tickets and messages are blocked; nothing was saved | Wait; reads and closing keep working | | 503 `SUPPORT_UNAVAILABLE` | Support is temporarily down, and a write that got this answer may or may not have been saved | Look it up by its `client_key`, or send it again with the same key and body after a few minutes |