Troubleshooting

The server answers problems with an HTTP status and a message that says what to do. Errors inside a tool call (the wrong input, a missing record) come back as a tool result with isError: true and the message as text. The agent can read it and try again.

Connecting

Status	Message	Fix
401	Send your API key as Authorization: Bearer <key>.	The client sent no Authorization header. Check the header name, and that the value starts with Bearer and a space.
401	This API key is invalid, expired or revoked.	Make a new key. Check that you copied all of it, with no spaces or line breaks.
401	This access token is invalid or has expired. Sign in again from the app.	An app that signed in with OAuth refreshes its token and tries again. If it can't, sign in again from the app. See Signing in.
401	This key's creator is no longer an owner or admin of the workspace, so the key no longer works.	An owner or admin makes a new key, or connects the app again.
403	The MCP server takes agent keys. Use /api/v1 with this key, or create an agent key on the workspace's API & agents page.	Make an agent key. API keys work with the REST API only.
405	Method not allowed. Send MCP requests as POST.	The client tried a GET stream or a session. Use the Streamable HTTP transport: everything is a POST.
406	Not Acceptable	Send Accept: application/json, text/event-stream.
429	More than … calls a minute through this key.	Too many calls through the key. Wait until the minute rolls over. See rate limits.
429	Too many calls from this network address. Wait a minute, then try again.	Your address passed the ceiling across all keys. Wait for the Retry-After seconds.

Every 401 carries a WWW-Authenticate header that says where to sign in, with error="invalid_token" added when a key or token was sent:

WWW-Authenticate: Bearer realm="JustDocs", resource_metadata="https://tryjustdocs.com/.well-known/oauth-protected-resource/mcp", scope="read documents send"

An OAuth client starts signing in from resource_metadata. A client using a key can ignore it.

Signing in

These come up when a client signs in with OAuth.

What you see	Fix
The client couldn't sign in, or couldn't find the server's OAuth details	Check the URL is exactly https://tryjustdocs.com/mcp: no trailing slash, not www., nothing after /mcp. The resource metadata names that URL, and clients refuse to sign in when the URL you gave differs from it. Remove the connector and add it again with that URL.
This app's registration wasn't recognized. Remove it in the app and add it again.	JustDocs couldn't read the document that describes the app, usually because the app's site didn't answer it just then. Wait a minute and try connecting again before removing anything. If it keeps happening, remove the connector in the app and add it again. A registered app that nobody connects is removed after 30 days, so an app that waited that long has to register again.
The app asked to send you back to an address it didn't register. Try connecting again from the app.	Remove the connector and add it again. If it keeps happening, the app's setup is wrong. Tell its maker.
The app didn't say who it is. Try connecting again from the app.	Start again from the app.
This sign-in has ended	Sign-ins last 10 minutes, and work only in the browser that started them. Start again from the app, and finish in the browser window it opens.
… sent a request JustDocs can't accept	The app's request had a mistake, named on the page. Return to the app and try again. If it keeps happening, the app needs fixing.
A workspace can't be chosen	You can connect apps to your personal workspace, or to a team where you're an owner or admin, once your email address is confirmed. Below Teams & Platform, a workspace with 3 active agent keys can't take another. The page gives the reason beside each workspace.
Your personal workspace can have 3 active agent keys, and a connected app counts as one. Revoke one first.	Revoke a key or disconnect an app you no longer use on the API & agents page, then connect again.
On its plan this team can have 3 active agent keys, and a connected app counts as one. Revoke one first, or move the team to Teams & Platform.	Revoke a key or disconnect an app on the team's API & agents page, or move the team to Teams & Platform, then connect again.
A workspace can have 25 active keys, and a connected app uses one. Revoke one first.	Revoke a key you no longer use on the API & agents page, then connect again.
Approve the app from its JustDocs page.	Approve on the page the app opened, not from another site or tab.
Take a moment to read this, then press Connect again.	Connect works once the page has been in front of you for a moment, focused or with the pointer over it. Press it again.
Too many sign-ins started from this address. Wait a minute, then try again.	Wait a minute.
The app asks you to sign in again, or reports invalid_grant	The sign-in ended: the app was disconnected on the API & agents page, its key expired, it was replaced by newer sign-ins, its refresh token went unused for 30 days, or a refresh token was used twice. Sign in again from the app.
401 with error="invalid_token" right after signing in	Access tokens last an hour. The app should refresh and try again; if the refresh fails, sign in again.
The app is connected, but its sends never go out	Working as intended. A connected app is an agent key, so its sends wait for an owner or admin under Approvals.
Connecting again didn't add a key	Working as intended. Connecting the same app to the same workspace again updates your key's limits.

An app that registers itself can get 429 More than 60 new apps registered from this address in an hour. The same app registering again doesn't count. Wait for the Retry-After seconds.

Tool results

Message	Meaning
Tool … not found	The key's permissions don't include that tool, so the server doesn't offer it. Keys can't be changed: make a new key with the permission. (Through the REST API, the same call returns 403 This key doesn't have the "send" permission.)
Waiting for an owner or admin of the workspace to approve this. Nothing has been sent yet; check get_approval.	Working as intended. An owner or admin decides under Approvals.
This key can only send to example.com. Not allowed: …	An address is outside the key's recipient domains.
This key has sent its 20 for the last 24 hours.	The key's daily send limit. Raise it on a new key, or wait.
This workspace has 500 approvals waiting. Ask again once some are decided.	Decide some approvals first.
Add a recipient for each signing role in the document: client, provider	Each role in the documents needs a recipient with that role_key.
This request is already waiting for approval, asked for by another key.	Another key's approval is pending for this request.
This Idempotency-Key was already used for a different call (or request)	The same idempotency_key was used for something else. Use a new one for each distinct action.
A call with this Idempotency-Key is still in progress; retry shortly	The first call is still running. Retry with the same key in a moment.
No template with this id in this key's workspace, "Northwind" (or its creator can't see it). A key works only in the workspace it was made in; get_workspace says which.	The id is in another workspace, or nowhere, or the key's creator can't see it. A template made in your personal workspace isn't in a team's, and the other way round. Use list_templates, or make the key (or connect the app) in the workspace that has the template. get_document and create_signing_request say the same of a document. See Workspaces.
This id is a document, not a template; list_templates lists templates.	get_template takes a template's id and was given a document's. Use list_templates. start_document says "This document is not a template" of the same mistake.
This workspace's plan keeps up to 3 saved templates. Delete one you no longer use, or upgrade the plan.	create_template reached the plan's limit. A person deletes a template in the app, or an owner changes the plan. See Plans and limits.
This document is too long to save. Split it into smaller documents, or shorten long fill-in values that repeat.	The template's text, or a document's fill-in values, made it too long.

Creating templates

Messages from create_template. A mistake in the text names its line.

Message	Meaning
Line 3: "{{Client Name}}" isn't a fill-in: write {{key}} or {{key|Label}}, key in lowercase letters, numbers and _, label up to 100 characters	A fill-in's key is lowercase, such as {{client_name}}, with any label after a |.
… isn't a signing field: write [[type:role]] or [[type:role|Label]], role in lowercase letters, numbers and -, label up to 100 characters	The same for a field, such as [[signature:client]].
… isn't a field type. Use signature, initials, date_signed, text, checkbox, full_name	A field's type is misspelled.
Say who signs: list roles, or write fields such as [[signature:client]]	The text has no signing fields and roles wasn't given.
The text has fields for …, which roles doesn't list	A field's role isn't in roles, often a typo. Add it to roles or correct the field.
Every field for client is optional. …	Give each role at least one required field: one without ?.
fill_ins lists …, which the text doesn't use.	Each key in fill_ins must appear in the text.
Paid documents are drafted by the legal questionnaire and bought one document at a time, so they can't be saved as templates	That library_entry is a paid document. Choose another, or write the text.
… is a packet; save its entries as templates one at a time: …	Copy each entry the message names.
Library entry not found	No library entry has that slug. The reference lists the ones that can be copied.
… is planned and not available yet	That library entry can't be used yet. Choose another, or write the text.

Workspaces

An agent that finds no templates, or can't find one it was given, is usually in another workspace from the one it expects. A key works only in the workspace it was made in:

1. Call get_workspace. Its name is the key's workspace, "Personal" for a personal workspace. list_templates names it too, beside the list.
2. If that isn't where the template is, make a key on that workspace's API & agents page, or connect the app again and choose that workspace. A template can also be made where the key is, with create_template or the library's Save as template.

The agent doesn't see the tools

• Check the client lists justdocs as connected. In Claude Code, run /mcp.
• A key with only read sees eight tools. For the rest, make a key with documents and send as well.
• Some clients cache the tool list. Reconnect or restart the client after you change the key.

Nothing reaches JustDocs

The key's last used time on the API & agents page is updated when the key is used, at most once a minute. A connected app's key is updated the same way. If it never changes, the client isn't reaching the server. Check the URL (https://tryjustdocs.com/mcp, no trailing slash or path) and any proxy between the client and the internet.

Still stuck

Email support@tryjustdocs.com with the time, the tool and the message. For a connected app, name the app and the workspace. Never send a key or token itself; a key's first characters (jd_live_…) are enough.