When something doesn’t work

Start with the smallest request you can check. Reading one page of posts or one month of your calendar is easier to diagnose than a workflow that drafts, schedules, and publishes all at once.

Keep the response status and the operation you attempted. Do not copy your API key, Authorization header, or private post content into logs or support messages.

The API returns 401

The request has not authenticated successfully.

Check that you used the full key, not the shortened prefix shown in the dashboard, and that it has not been revoked. Use the REST authentication header documented for that endpoint.

For MCP, the credential must also be sent during initialization and discovery, not just when calling a tool. OAuth access tokens, API keys, and refresh tokens are not interchangeable.

Do not keep retrying the same invalid credential. Correct the configuration or reconnect first.

A website REST request returns 404

The post, post-details, auto-comment, and latest-template reads deliberately return generic failures. HTTP 404 can mean a missing resource, an invalid or revoked key, an account access restriction, or a failed upstream read. It does not always mean the URL is wrong or the account has no data.

Check the website origin, exact path, and x-youscaleit-api-key header against API read endpoints. These website paths do not have a /v1 prefix. Do not include browser cookies when checking API-key access: a browser session takes priority over the key.

Unmatched ordinary /api paths return HTTP 404 with {"success":false}. Existing endpoints can have their own error responses. A successful empty list instead has success: true and an empty result array.

The REST action endpoints also use generic 404 responses for input validation failures, backend rejections, and timeouts. For drafts, use the composer-style isPostUnified field and named platform objects, not the MCP isUnified/platforms/socials payload. Check that both website and backend have the matching draft revision. Never automatically retry a failed write: it may already have completed.

The request returns 403

A forbidden response can mean missing permissions, an account access restriction, or an Origin restriction. Read the error rather than assuming every 403 has the same cause.

For OAuth MCP calls, insufficient_scope means the connection lacks a required permission. Approve additional access only if you actually want the assistant to perform that action.

For API keys, check the account’s eligibility and endpoint access. The legacy MCP API-key path also rejects browser requests from a different Origin. Moving the key into browser code is not a solution.

MCP reports conflicting credentials

Send either the Authorization header or the custom MCP API-key header, not both. Remove the unused header from the connector’s configuration, even if it contains the same key.

OAuth sign-in does not appear, or registration fails

OAuth may be unavailable in that deployment, or the client may not support the required registration flow. Use automatic dynamic registration, not a CIMD URL. Do not put an API key in the client ID or client-secret fields.

If supported, an API-key connector is an alternative for calendar reading. It does not unlock OAuth-only write tools.

Assistant settings and feature availability vary between clients. A setup option shown in one product or plan may not exist in another.

MCP returns a protocol or request error

Tool argument errors can also appear inside an MCP result rather than as an HTTP error. Check the protocol result and its error indicator, not just the HTTP status. A client SDK normally handles the transport details for you.

There are no posts in the result

An empty array or a zero total in a successful response is a valid result. For the website post list, the array is data.data and the total is data.total. Calendar and auto-comment arrays are directly in data. Check:

• You are connected to the intended account or workspace.
• The month and year are correct.
• Status and platform filters match the content you want.
• You are not requesting a page or offset beyond the end of the result.

Calendar results include more than pending posts. If you filter them yourself, make sure that filtering is not hiding the entries you expected.

Dates look wrong

Keep timezone information when reading timestamps. Calendar period boundaries come from the backend’s calendar timezone, not automatically from the device running your script.

For MCP scheduling, use a future timestamp with an explicit timezone offset or UTC marker. “Monday at 9” is not enough if the account owner and assistant are in different timezones. Ask the assistant to confirm the exact date and timezone before scheduling.

A draft edit removed its media

The MCP draft-edit tool replaces the draft’s content. Omitted media is cleared; it is not preserved as a partial update would preserve it.

For MCP, read the current draft before editing, include the fields you want to keep, and retain the existing composition mode and platform set.

REST draft editing has different semantics. It supports switching modes, preserves omitted parent values, and resets platform overrides when switching to unified mode. Switching away from unified mode seeds empty platform text and copies shared attachments before applying submitted values. Read REST editing and media semantics before converting a draft; the REST request does not show the composer’s confirmation dialog.

Publishing returned a job ID, but there is no live post yet

A job ID means the publishing request was queued for processing, not that the social platform has published the content.

Use the MCP publishing-status tool or the REST publishing-status endpoint to distinguish pending, processing, completed, and failed work. A saved social connection can also need attention even though it still appears in the destination list.

A write timed out

Do not assume it failed before doing anything. Publishing, scheduling, draft creation, or reposting may have completed even if the response did not reach you.

Check the job status, saved draft, calendar, repost schedules, or dashboard as appropriate. Do not automatically repeat an uncertain write; that can create duplicates.

The service returns 429 or a temporary server error

For 429, slow down. Honor Retry-After when the response provides it. No universal requests-per-minute allowance is promised by this initial reference.

For temporary 502 or 503 responses, retry reads with a bounded delay and backoff rather than an immediate loop. For writes, check the outcome before deciding whether to retry.

A credential was exposed

Revoke the affected API key, or disconnect the affected OAuth agent, then replace the integration’s credentials as needed. Review recent activity and any future schedules separately.

Removing a credential does not undo actions that already happened, and it does not automatically cancel scheduled work.

If you need help, use YouScaleIt contacts. Include the operation, approximate time and timezone, client name, and sanitized error message. Never include the credential itself.