Support reference
Section titled “Support reference”Lookup tables for support. Every parameter and response field is in the Support tickets API reference.
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
Section titled “Access”Who can use support is on the guide. 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
Section titled “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:
{ "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:
{ "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
Section titled “Ticket lifecycle”Statuses and reopening are on the guide. 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.
Tiers and quota
Section titled “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:
{ "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
Section titled “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
Section titled “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
Section titled “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
Section titled “Safe retries”How client_key works is on the guide.
| 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
Section titled “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
Section titled “Privacy and retention”Who reads tickets is on the guide.
| 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
Section titled “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 |
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 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 |
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 |
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 |