Skip to main content
This page lists every error code the connector publishes. Each row says where the code arrives, what caused it and the action to take. A code outside this list is not something Coffee Chats sends. Handle errors and retries is the procedure that uses this table.

​
Where these codes arrive, and under which HTTP status

Every code on this page arrives inside a normal, successful protocol response. The HTTP status is 200 in all of them, and so is the status on a read tool’s failure text. An agent that branches on HTTP status alone will never see any of these. These are the HTTP statuses the protocol address answers with. Only the first carries a code from this page; the rest mean the call never reached a tool. Any status outside this table is not one the connector produces on purpose. Treat it as undefined, report it, and do not retry blindly. A 429 answer carries these headers: RateLimit-Policy, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset and Retry-After. Wait the number of seconds in Retry-After before calling again. The limits page states what each limiter counts.

​
Codes in a failing result

These arrive inside the error object of a write result whose status is failed. In every one of them, nothing was written. The result object describes the object they sit in.

​
Codes in a cancelled or uncertain result

​
Codes in a retry hint

These two never arrive in a failing result. They ride under _meta beside an accepted result, and nothing has failed when you see one.

​
What the retryable boolean is worth

Every error object carries a retryable boolean, and every retry hint carries one too. They do not mean the same thing, so read them separately. In a retry hint, retryable is always true. It is fixed by the contract and tells you nothing the hint’s presence had not already told you. In an error object, retryable is false on every failure the connector maps today, with one exception: OUTCOME_UNKNOWN copies the flag from the record it is reporting, so it can arrive as true.
Do not branch on retryable alone. A true on OUTCOME_UNKNOWN does not mean the change may be sent again. It means the outcome is unknown and a read has to settle it first. Use the Action column above, which is the authority.

​
How long to keep retrying

The connector sets no retry ceiling and no backoff schedule. The only delay it ever states is retryAfterMs in a retry hint, which the contract bounds to between 1 and 5,000 milliseconds and which every write tool that issues one sets to 1,000. Everything else is your choice. The following is guidance, not a rule the connector enforces. Wait the delay the hint gives you. Cap the number of attempts at a small number your agent can explain to a student. Stop once a result is completed, failed, cancelled or uncertain, because nothing moves out of those four. One connection may make 120 calls a minute, and a loop spends that budget on one change.

​
Failures that carry no code

A read tool’s failure carries no code. It arrives as a protocol error holding one line of text, and that text is one of three. This section is the reference for all three, and the other pages link here rather than state the rule again. The first text is the fixed one, and almost every failure carries it:
Protocol error envelope
A write that fails before it produces a result of its own arrives this way, and so does a call to a tool whose permission was not granted. There is nothing in it to branch on. The reason is withheld on purpose, because the reason could itself describe data the connection was not allowed to see. The second text arrives when a tool looks up one record by its id and your account has no such record. The text names the kind of record and nothing else:
A lookup that found no record of yours
Eight kinds of record answer this way, and the text names the kind the tool was asked for: application, booking, calendar source, campaign, contact, event type, meeting and posting. A lookup of anything else, including a review request by its operationId, answers with the fixed text instead. The text is the same whether that id never existed or belongs to another student’s record, so it says nothing about any account but yours. It carries no id and no code. An agent may act on it: stop asking for that id, and call the matching list tool to find the ids your account does have. One of the eight kinds has no list tool. jobs.postings.get reads a posting from a catalogue shared with every signed-in student, so the connector lists no postings. When the text names a posting, search for it with jobs.search instead, or ask the student which posting to read. The third text says why a value is withheld instead of which record is missing. A meeting whose transcript Coffee Chats does not hold answers meetings.transcript.list with:
A transcript Coffee Chats does not hold
A call refused for rate limiting carries no code from this page either. It is the 429 answer described at the top, and the limits page states what each limiter counts.

​
Next steps

Handle errors and retries

The three shapes a failure arrives in, and the five things never to do.

Tool reference

Each tool’s own page lists the codes that tool can return.