The Partner FAQ and Error Decoder

Every partner asks the same ten questions, and every failed connection produces one of about ten error strings. That is not a complaint about partners; it is the nature of a service where everyone connects the same way. It means the answers can be written once. A partner FAQ is the list of those questions with the answers already written. An error decoder is the list of those strings. Each is translated into what it means, what the partner should do next, and what you should check. Together they turn most support tickets into a paste.

This article gives you both, filled in for a synthetic server, plus a set of support macros. These are pre-written replies with blanks, which support staff paste and complete rather than composing from scratch. Each error string is real, quoted as a partner would paste it. This article is part of our Partner Onboarding and Support Documentation series. It is the document that keeps working after onboarding ends, because partners keep connecting long after they have stopped reading the guide.

Why the Same Ten Questions Keep Arriving

The questions repeat because the situations repeat. A new admin at the partner inherits the connection and does not know which folder to use. A client is reinstalled and asks about a fingerprint nobody remembers approving. A file vanishes from the inbox and someone assumes it was lost rather than collected. None of these people has read your guide. That is because it went to their predecessor, or is on page two of a ticket from a year ago. The FAQ exists for the person who has the question now.

Harvest the questions from your own ticket queue rather than guessing. Export the last year of partner tickets, read the subject lines, and group them. The top ten account for most of the volume. The first draft of the FAQ is those ten with the best answer you have already written. (You have written each at least four times. One of the four was good.)

Answer in the partner's terms, not yours. The partner does not want to know that your server enforces a jail. They want to know that the folder they see on login is the right one. Each answer says what to do, then why, in two or three sentences, and points at the guide for the values. The FAQ never repeats a value that is on the guide, because two copies of the port number is one copy that will be wrong.

The Partner FAQ, Written Once

The document below is Acme's FAQ as sent to every partner with the connection guide. It is deliberately short. A FAQ with forty entries is a manual. Manuals are not read at four in the afternoon by someone with a broken upload.

ACME FILE TRANSFER - PARTNER FAQ                                            Version: v3

Q1  Which protocol and port do I use?
A   SFTP on port 22, or FTPS on port 21 with passive mode, as stated in section 1 of your
    connection guide. Plain FTP is not offered.

Q2  My client is asking me to trust a fingerprint. Should I?
A   Compare it with section 2 of your connection guide. If it matches, yes. If it does not,
    do not accept it; contact us with the fingerprint you were shown.

Q3  Can you resend our password?
A   Passwords are never sent by email. Ask your technical contact to request a reset; the new
    password is delivered by phone to the contact named on your intake form.

Q4  Which folder do I upload to?
A   /inbox, exactly as written, lower case. /outbox holds files we send to you. There are no
    other folders.

Q5  Why can't I delete or overwrite a file in /inbox?
A   By design: once a file is uploaded it is ours to process, and a second upload with the same
    name is refused so a file is never silently replaced. Contact us if a file must be withdrawn.

Q6  My file disappeared from /inbox. Was it lost?
A   No. Files are collected from /inbox by our processing job, usually within 15 minutes of
    arrival. A file that has disappeared has been received.

Q7  How do I know you received a file?
A   For test files, an acknowledgement appears in /outbox (see the test procedure). For live files,
    disappearance from /inbox is receipt. If a file is still there after an hour, contact us.

Q8  Can we use plain FTP? Our system only supports FTP.
A   No; plain FTP sends credentials and data unencrypted. Most systems that "only support FTP"
    support FTPS with a setting change. Contact us and we will help.

Q9  Our IP address is changing. What do we do?
A   Tell us the new address at least five working days before the change. Both addresses are
    permitted during the changeover, and the old one is removed when you confirm.

Q10 What should I include when I report a problem?
A   Your username, the time of the attempt in UTC, the exact error text copied from the screen,
    and the file name. Send to transfer-support@example.com; hours are in section 6 of your guide.

Notice Q5 and Q6. Both describe behavior that is correct and looks like a fault. Both cause tickets in proportion to how surprising they are. Any rule a reasonable partner would misread as a failure belongs in the FAQ, explained as a design choice. "By design" is a phrase partners accept when it is followed by a reason.

The Error Decoder

Partners do not describe errors; they paste them. That is good. A pasted string is exact, and an exact string maps to a short list of causes. The decoder below covers the strings behind nearly every partner ticket on an SFTP and FTPS service. It gives the layer each lives at, the usual cause, the partner's next step, and your check. Keep it where support staff can see it; send the relevant row when a partner pastes the string.

The strings are grouped by layer for a reason. "Connection timed out" and "Connection refused" are network problems; no amount of password checking will fix them. "Permission denied (publickey)" and "530" are authentication; the network team cannot help. "425" is the FTP data channel, a layer that has confused people for as long as FTP has existed. When you cannot tell which layer a failure lives at, work upward from the network, one layer at a time. That discipline is the layered troubleshooting method. The authentication and connectivity layers are treated in detail in troubleshooting authentication failures and troubleshooting the connectivity layer.

Three strings deserve more than a row. "Permission denied (publickey)" names, in the brackets, the methods the server would have accepted. (publickey,password) means both are allowed and neither worked. (publickey) alone means no password would ever have helped, and the ticket is about the key. That bracket saves a round trip when you read it. "Host key verification failed" is the one where the wrong advice is dangerous, and it has its own note below. And "425" is the reason the guide carries a passive port range at all. The full diagnosis is in diagnosing FTP mode failures. The reply codes in general are covered in FTP commands and reply codes.

Support Macros for the Rest

A macro is a saved reply with blanks, kept where support staff can paste it and fill the blanks in under a minute. Macros exist because a reply written fresh each time is written differently each time. A partner who receives three explanations from three people stops trusting all of them. The set below covers the replies that follow from the decoder. Fill every blank; a macro sent with a blank in it is worse than no reply.

M1  NEED THE FOUR FACTS
Thanks for the report. To look into this we need four things: the username, the time of the
attempt in UTC, the exact error text copied from the screen, and the file name (if any).
Reply with those and we will check our logs for that session.

M2  ADDRESS NOT PERMITTED
Our logs show no connection from <ADDRESS_ON_FILE> at <TIME>. Please confirm the public
address the connection leaves from (your network team can tell you; it is the address the
internet sees). If it differs, send the new address and we will permit it alongside the old.

M3  KEY NOT ACCEPTED
The server rejected the key offered at <TIME>. The key we hold for username <USERNAME> has
fingerprint <FINGERPRINT_ON_FILE>. Please run "ssh-keygen -lf yourkey.pub" on the key your
client is using and reply with the fingerprint it prints. If it differs, attach the .pub file
of the key you intend to use and we will install it.

M4  HOST KEY CHANGED (only after confirming a rotation)
The server's host key was changed on <DATE> as announced in change notice <NOTICE_ID>. The
new fingerprint is <NEW_FINGERPRINT>; it is also in version <GUIDE_VERSION> of your connection
guide, attached. Remove the old entry with "ssh-keygen -R sftp.example.com", reconnect, and
confirm the fingerprint shown matches before accepting it.

M5  DATA CONNECTION (425)
Login succeeded and the failure is on the data connection. Please set your client to passive
mode and ask your firewall team to permit outbound connections to ports <PASSIVE_RANGE> on
<SERVER_ADDRESS>, as listed in section 1 of your connection guide. Then retry a listing.

M6  PASSWORD RESET
We do not send passwords by email. A new password has been set and will be given by phone to
<TECHNICAL_CONTACT> at <PHONE_ON_INTAKE_FORM> within <HOURS> hours.

Macros are not a substitute for reading the ticket. M1 is the reply when the ticket lacks the facts, not the reply to every ticket. A partner who supplied all four facts and receives M1 anyway has learned something about your support desk. It is something you would rather they had not learned. Read first, then paste. The same principle, for customers rather than partners, is developed in customer exchange support.

Two macros depend on the server telling you something. M2 needs a log that records the source address of every attempt, accepted or refused. M3 needs an authentication log that says which key was offered. A server that keeps a per-session activity log with source addresses and maintains per-address allow and block lists gives you both from one screen. Sysax Multi Server is one such server. Lockout behavior turns three bad passwords into a 530 and a ticket. Lockout behavior is designed deliberately in authentication failures and lockouts.

Where the FAQ Lives and How It Grows

Send the FAQ with the connection guide on day one. Keep it where the partner can find it without a ticket. That could be a page on your partner portal if you have one, or the same attachment on every reply from the support mailbox. A FAQ the partner cannot find is a FAQ you will be asked to send, which is a ticket, which is what the FAQ exists to prevent.

Grow it one entry at a time. When a ticket arrives with a question not in the FAQ, answer the ticket, then add the entry, in that order. When a question stops arriving, leave the entry a year and then retire it. Questions come back when the partner's staff turn over. Version the FAQ like the guide, with a number in the header. That way, a partner quoting "Q6" and you reading "Q6" are looking at the same text. That rhythm is the subject of keeping partner documentation current. The article also covers the change notices that accompany a key rotation or an address move.

I have watched a FAQ reach twenty-two entries and stop being read. The cure was to cut it back to ten and move the rest into the decoder and the macros. There, the remaining entries are looked up rather than read. Ten questions, nine strings, six macros. That is the whole support library for a partner service, in three short documents.

A Short Story About Three Answers

Acme rebuilt its transfer server over a weekend and, in the process, generated a new host key. On Monday, three partner admins pasted "Host key verification failed" into three tickets. Those tickets went to three different people on Acme's support desk. The first suggested a network problem and asked the partner to check their firewall. The second correctly identified a key change and sent the new fingerprint. The third told the partner to delete their known_hosts file and try again, which worked. It would also have worked had the server been an impostor. By Wednesday the partners had compared notes. By then, Bluewater Bank's security team had written to ask which of the three answers was Acme's official position. The decoder entry and macro M4 were written that afternoon, by the person who had to reply to the bank.

Three people, three answers, one server. The failure was nobody's; the correct answer simply existed only in the head of the second person. Writing it down is the entire fix.

The Version to Tell a Colleague

Partners ask ten questions and paste ten strings. Write the answers once. Write a FAQ that explains the behaviors that look like faults. Write a decoder that maps each string to its layer, cause, next step, and your check. And write six macros for the replies that follow. Read the bracket after "Permission denied". Never tell anyone to delete known_hosts without confirming a key change. And ask for the four facts on every document a partner holds. Grow the FAQ one entry per new question and cut it when it stops being read.

The decoder assumes the partner has run the steps in the self-serve test procedure. The procedure's failure reports name the step and carry the facts. The values the FAQ refers to live in the connection guide. For the mechanics behind the most dangerous entry, host keys and known_hosts explains what the client is actually checking.

Frequently Asked Questions