Errors

One error vocabulary across MCP and REST, with what each code means and what to do about it.

Both transports use the same codes, so a client that handles these six handles everything the API can throw. Over REST each code maps to an HTTP status; over MCP the code arrives in the tool result.

Code	HTTP	Meaning
`BAD_REQUEST`	400	The input failed validation.
`UNAUTHORIZED`	401	No credentials, or credentials that are no longer valid.
`FORBIDDEN`	403	Authenticated, but not allowed to do that.
`NOT_FOUND`	404	No such resource, or it is not public.
`TOO_MANY_REQUESTS`	429	Rate limited.
`INTERNAL_SERVER_ERROR`	500	Our fault.

Shape

{
    "error": {
        "code": "FORBIDDEN",
        "message": "This URL is already listed at /products/example/."
    }
}

The message is written to be shown to a person or read by an agent. Branch on code, never on the wording of message.

What to do about each

BAD_REQUEST

Validation failed against the same schema the browser form uses, so the message names the field. The common ones are more than three categories, a tagline over the length limit, and a url that is not a URL.

Fix the input and retry. Retrying unchanged will fail identically.

UNAUTHORIZED

On REST: the Authorization header is missing, malformed, or the connection behind the token was revoked. Pair again at /connect/ and use the new token.

On MCP you will usually not see this at all. A write tool on an unpaired session returns the approval link instead, because a pairing prompt is more useful to an agent than an error. See Authentication.

FORBIDDEN

You are authenticated, but the action is not yours to take. In practice this is one of three things: the URL is already listed, you are inside the relaunch cooldown (the message carries the date you become eligible), or you asked about a product owned by somebody else.

None of these are retryable as sent. Run check_launch_readiness to see the duplicate and relaunch state before you submit.

NOT_FOUND

The slug does not match a live product. Note that a product which exists but has not launched yet answers NOT_FOUND as well, on purpose: the public API never confirms the existence of an unpublished listing.

TOO_MANY_REQUESTS

Wait and retry once. Nothing was created, so retrying is safe. Details on Rate limits.

INTERNAL_SERVER_ERROR

Something broke on our side. Retry once after a short pause. If it persists, mail support@nicklaunches.com with the endpoint or tool name and roughly when it happened.

Errors that are not errors

An unpaired write is not a failure.

The first submit_product or get_my_launches call on a fresh MCP session returns a readable message with an approval link rather than UNAUTHORIZED. Do not treat that as a hard failure and do not retry it in a loop: it is asking a person to click once, then the same call succeeds.

A failing readiness check is a successful call.

check_launch_readiness returning checks with status: "fail" is a 200. The audit worked; the site is the thing that needs attention.

Debugging over REST

curl -i https://nicklaunches.com/api/v1/products/does-not-exist/

-i prints the status line, which tells you whether you are looking at an application error or at something more basic, for example a 308 because the trailing slash was dropped.

Was this page helpful?