Skip to content
Game Market Copilot Docs
Esc
↑↓navigate↵open⌘Jpreview
On this page

Troubleshooting

Common GMC error responses, their causes, and how to resolve them across the API, CLI, and MCP.

GMC’s REST API, CLI, and MCP surfaces share the same error shape and error codes. This page covers the codes you are most likely to hit and how to resolve each one.

Error response shape

Every error response, from the REST API and from the MCP proxy, follows the same JSON shape:

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Human-readable description",
    "param": "optional_field_name",
    "requestId": "req_..."
  }
}

param is present when the error can be attributed to a specific request field. requestId is always present; include it when contacting support so the request can be located in server-side logs.

Error codes

Code HTTP status Meaning What to do
BAD_REQUEST 400 One or more request parameters are invalid. Check the param field and the message for which parameter and why.
INVALID_TAG 400 One or more tag slugs in a filter are unrecognized. The response includes suggestions for close matches. Fetch the current valid tag list from /api/v1/tags rather than hardcoding tag slugs.
UNAUTHORIZED 401 The request is missing a credential, or the credential is invalid. The most common cause is a mangled pasted API key (a stray newline or truncated character). Re-copy the key exactly from Settings → API rather than retyping it.
PLAN_REQUIRED 402 The requested feature needs a paid plan. Check /plans for which plan unlocks the feature, then upgrade from Settings → Billing.
FORBIDDEN 403 The credential is valid but not allowed to perform this action. A common case is presenting an MCP-scoped OAuth token to the REST API, or vice versa; use the credential type that matches the surface you are calling.
QUOTA_EXCEEDED 429 The workspace’s monthly credit allowance is exhausted. Wait for the monthly reset (start of the next UTC month), or buy a credit pack. See /plans.
RATE_LIMITED 429 Too many requests in a short burst. Honor the Retry-After header on the response and slow down your request rate before retrying.

QUOTA_EXCEEDED and RATE_LIMITED are both HTTP 429 but represent different problems: quota is about the monthly credit allowance running out, while rate limiting is a short-window burst guard independent of remaining credits.

Prefer aggregates over paginating full lists

If you need a count, a total, or a distribution rather than individual game records, use an aggregate or count-style endpoint instead of paginating through every matching game with a list endpoint. Aggregates are cheaper in credits and give a population-true answer, whereas paginating a large list end to end is both slower and more expensive for the same question.

CLI: gmc alias conflicts with zsh git plugins

Some zsh configurations (for example, certain oh-my-zsh git plugins) define a shell alias named gmc that shadows the GMC CLI binary. If running gmc does something unexpected, check for an existing alias with type gmc or which gmc. The CLI also installs under the alias gmcp, which avoids the conflict; use gmcp in place of gmc if your shell has claimed the shorter name.

CLI: gmc login fails with a non-JSON response

gmc login opens a browser-based OAuth flow and expects a JSON response on callback. If it fails with a non-JSON or HTML response instead, a corporate proxy or network access gateway may be intercepting or rewriting the callback request. Try the login flow from a network without such interception (for example, off the corporate VPN or proxy), or contact your network administrator about allowing the callback domain through unmodified.

Getting help

If none of the above resolves your issue, contact gamemarketcopilot.com/contact and include the requestId from the error response so the request can be traced.

Was this page helpful?