Error Codes

Overview

This page covers all error responses you may encounter when using f2d, across both the REST API and MCP interfaces. Errors are grouped by HTTP status code.

400 — Bad Request

The request is malformed or missing required parameters.

REST API

{ "error": "q is required" }

Cause: The q (query) parameter is missing from the request body or query string.

Solution: Include a search query in your request:

curl -s -X POST "<your-api-url>/v1/search" \
  -H "Content-Type: application/json" \
  -H "x-api-key: <your-api-key>" \
  -d '{"q": "your search query"}'

MCP

{
  "result": {
    "content": [{ "type": "text", "text": "query is required" }],
    "isError": true
  }
}

Cause: The query parameter is missing from the tools/call arguments.

Solution: Include "query" in the arguments object:

{
  "params": {
    "name": "search_jobs",
    "arguments": { "query": "your search query" }
  }
}

Note: REST API uses q while MCP uses query as the parameter name.

401 — Unauthorized

Authentication credentials are missing (MCP only).

MCP

{
  "jsonrpc": "2.0",
  "error": { "code": -32600, "message": "Unauthorized" },
  "id": null
}

The response includes a WWW-Authenticate header:

WWW-Authenticate: Bearer resource_metadata="<discovery-endpoint-url>"

Cause: No Bearer token was provided in the request.

Solution: MCP clients (Claude Desktop, Claude Code) handle this automatically by initiating the OAuth login flow. For manual testing, obtain an Access Token first — see JSON-RPC Examples.

403 — Forbidden

Authentication credentials are invalid.

REST API

{ "error": "Invalid API key" }

Cause: The x-api-key header is missing or contains an invalid key.

Solution:

• Verify your API key is correct
• Ensure the header name is exactly x-api-key (lowercase)
• If using the CLI: run f2d configure to reset your key

MCP (API Key Fallback)

Same response format as REST API. This occurs when using API key authentication with MCP (supported for some clients as a fallback).

Solution: Use OAuth authentication instead, or verify your API key.

429 — Rate Limited

Too many requests in a short time period.

REST API and MCP

{ "error": "Rate limit exceeded", "retry_after": 12 }

The response includes a Retry-After header with the number of seconds to wait.

Cause: You've exceeded the allowed request rate.

Solution:

1. Wait for the number of seconds specified in the Retry-After header
2. The retry_after value includes random jitter to prevent thundering herd
3. Implement exponential backoff in automated clients

The rate limit applies per API key (REST) or per user (MCP).

500 — Internal Server Error

An unexpected error occurred on the server.

REST API

{ "error": "Internal server error" }

MCP

{
  "jsonrpc": "2.0",
  "error": { "code": -32603, "message": "Internal error" },
  "id": 1
}

Cause: An unexpected server-side error.

Solution:

• Retry after a few seconds
• If the error persists, the service may be experiencing an outage — try again later

MCP-Specific Errors

These errors only occur on the MCP endpoint.

Not Acceptable (-32000)

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32000,
    "message": "Not Acceptable: Client must accept both application/json and text/event-stream"
  },
  "id": null
}

Cause: The Accept header is missing or doesn't include both required content types.

Solution: Add the required header:

Accept: application/json, text/event-stream

Unknown Tool (-32602)

{
  "result": {
    "content": [{ "type": "text", "text": "MCP error -32602: Tool nonexistent_tool not found" }],
    "isError": true
  }
}

Cause: The requested tool name doesn't exist.

Solution: Use tools/list to see available tools. Valid tools are search_jobs and list_cities.

Quick Reference