# Errors REST errors are JSON: `{ "error": { "code": "...", "message": "...", "retryAfterMs"?: number, "details"?: object } }`. MCP returns the same code and message as a tool error (isError true). Act on the code, never on the message text. ## invalid_argument HTTP 400 · SCN-400 · REST and MCP A field has the wrong shape. A required field is missing, a field is unknown, or a value does not match its type (the Convex validator's path and value are in the message). What to do: Fix the field named in the message. The operation's parameters list every accepted field with its type. ## invalid_request HTTP 400 · SCN-400 · REST and MCP The input was refused. A writer refused a value: a map link on a host that is not allowed, a title that is too long, a date that does not exist, too many items in a list. The message is the writer's own sentence. What to do: Change the value the message names and send the request again. Do not retry unchanged. ## invalid_json HTTP 400 · SCN-400 · REST The body is not a JSON object. A POST, PUT or PATCH body is not valid JSON, or is JSON but not an object. What to do: Send a JSON object with Content-Type: application/json. ## unsupported_image HTTP 400 · SCN-400 · REST Not a JPEG, PNG or WebP. An upload's bytes are not a JPEG, PNG or WebP file, or their dimensions cannot be read. The bytes are checked, not the Content-Type header. What to do: Convert the photo to JPEG or WebP and upload it again. ## image_too_large HTTP 400 · SCN-400 · REST The photo is too large. An upload is more than 6,000 px on a side. What to do: Resize to 2,048 px on the long side and compress before uploading. ## stale_editor HTTP 409 · SCN-409 · REST and MCP It changed since you read it. The row changed after the expectedUpdatedAt you sent (update_chapter, save_sales_page_draft). What to do: Read the row again, apply your change to the new version, and send it with the new updatedAt. ## unauthenticated HTTP 401 · SCN-401 · REST and MCP No API key. The request carries no key. Send it as Authorization: Bearer sk_sceniq_... (or X-Api-Key). What to do: Add the header. MCP clients take it in their server config. ## invalid_api_key HTTP 401 · SCN-401 · REST and MCP The key does not work. The key is unknown, revoked or expired. What to do: Ask the creator for a new key (studio, Settings, API keys). Keys are shown once, when they are created. ## api_scope_required HTTP 403 · SCN-403 · REST and MCP The key lacks a scope. A read-only key called a write operation, or a key without the publish option called publish_changes. What to do: Ask the creator for a key with the scope the message names. Never work around it. ## api_key_not_allowed HTTP 403 · SCN-403 · REST and MCP Only the creator can do this. The action is interactive only: putting a guide on sale, store visibility, archiving a guide, payouts, the account. A key never reaches it. What to do: Hand the step to the creator with its studio link (get_guide_readiness lists them in handoff). ## forbidden HTTP 403 · SCN-403 · REST and MCP The key has no creator. The key belongs to a creator account that is no longer active. What to do: Stop and tell the creator; the account needs attention in the studio. ## not_found HTTP 404 · SCN-404 · REST and MCP Not found. The id does not exist or belongs to another creator. The two answers are identical on purpose, so ids never reveal what exists. What to do: Read the id again from a list operation (list_guides, list_spots, ...). ## unknown_route HTTP 404 · SCN-400 · REST No such endpoint. No operation answers at this method and path. What to do: Check the path against the reference or the OpenAPI document. ## method_not_allowed HTTP 405 · SCN-400 · REST and MCP Wrong method. The path exists for other methods (the Allow header lists them), or a GET or DELETE reached the MCP endpoint. What to do: Use a method from the Allow header. The MCP endpoint only takes POST. ## guide_sold HTTP 409 · SCN-409 · REST and MCP The guide has buyers. delete_spot on a guide someone bought. Buyers keep what they paid for. What to do: Archive the spot instead: update_spot with archived true. ## conflict HTTP 409 · SCN-409 · REST and MCP The row's state refuses it. The request clashes with the row's current state. The message says what to change. What to do: Read the row again and follow the message. ## not_publishable HTTP 409 · SCN-409 · REST and MCP A publish gate is open. publish_changes while a gate is open: the agreement, no live spot, a live spot without a pin or a photo, no price. details.blocking lists each gate as { code, message }. What to do: Fix each blocking item (get_publish_status lists them), then publish only if the creator asks. ## not_live HTTP 409 · SCN-409 · REST and MCP The guide is not on sale. publish_changes on a draft or archived guide. A draft's first publish happens in the studio. What to do: Hand the creator the reviewUrl; putting a guide on sale is their click. ## no_changes HTTP 409 · SCN-409 · REST and MCP Nothing to publish. publish_changes when buyers already see every change. What to do: Nothing to do. get_publish_status shows the live version. ## agreement_outdated HTTP 409 · SCN-409 · REST and MCP The agreement needs accepting. A price change or a publish before the creator accepted the current creator agreement. What to do: Ask the creator to accept it in the studio, then try again. ## payload_too_large HTTP 413 · SCN-400 · REST and MCP The request is too large. A JSON body over 2 MB, an image over 6 MB, a batch upload over 19 MB, or an MCP message over 2 MB. What to do: Split the request (upsert_spots takes 25 spots per call) or compress the photo. ## rate_limited HTTP 429 · SCN-429 · REST and MCP Too many requests. Over a limit: requests per key per minute, per creator per hour, uploads per key per minute, or check_links per guide per hour. What to do: Wait for Retry-After (seconds) or retryAfterMs, then continue. Do not retry in a tight loop. ## internal_error HTTP 500 · SCN-400 · REST and MCP Something failed on our side. An unexpected failure. The message is hidden on purpose. What to do: Try once more after a short wait. If it repeats, tell the creator and write to creators@sceniq.earth with the time and the operation. ## unknown_tool HTTP 400 · SCN-400 · MCP No such tool. tools/call names a tool the server does not have. What to do: Call tools/list and use a listed name.