Skip to content
Quiet Social

Errors

This documentation is translated from French. Should the two versions differ, the French version prevails.

For each refusal from the API, this page answers a single question: should you retry?

Answer Meaning
No The same request will produce the same error. Fix the configuration, or give up.
After correction Fix the body or the header, then send again. The idempotency key remains usable.
Yes The cause is transient. Send the same request again, after a delay.

The two envelopes

API refusals carry a stable code in error.code:

{
  "error": {
    "code": "insufficient_scope",
    "message": "This client does not hold the « destinations:read » scope.",
    "required_ability": "destinations:read"
  }
}

error.code is the contract: it does not change. error.message is written for a person, and may be reworded: never compare it.

The API's messages are in English, whatever the language of your account and regardless of the Accept-Language header, business refusals included: draft and network rules, publication transitions, webhook addresses. Exception: the error of a target (targets[].error.message) that does not come from our publishing rules — a refusal by the network at publication time, a missing token, a network that is not configured, a technical failure of the delivery — may still be in French, or in the network's own words. Likewise, a target that failed before these messages were translated keeps its message in French, in the API as in webhooks, until it is retried. Rely on error.code and on the keys of errors, never on the text. Some codes carry additional fields, described below.

Request validation errors — missing field, wrong type, value outside the allowed list — keep Laravel's envelope, without error.code, with a 422 status:

{
  "message": "Send at least one destination.",
  "errors": {
    "destination_ids": ["Send at least one destination."]
  }
}

errors is keyed by field name. Its messages are in English, like the rest of the API.

Notable shape refusals, all as 422 on the field concerned:

  • a date that is not in ISO 8601 (« The date must follow ISO 8601, for example 2026-10-15T09:00:00+02:00. »);
  • media and media_ids sent together, or more than 10 media items;
  • more than 30 tags, or a tag that is empty or too long once formatted;
  • an override key a network does not allow (« « instagram » does not accept: « link_url » »), or an unknown network name;
  • on POST /webhooks, a URL refused by the guard, an event outside the catalog, or a brand_id that designates no brand of the workspace.

A robust client therefore reads error.code if it exists, and errors otherwise.

$response = $quietSocial->post('/publications', $payload);

if ($response->failed()) {
    $code = $response->json('error.code');          // null for a validation error
    $fields = $response->json('errors', []);        // present for a validation error
}

Decision table

Code Status Retry?
unauthenticated 401 No
insufficient_scope 403 No
plan_required 403 After an upgrade
workspace_suspended 403 After the suspension is lifted
account_pending_deletion 403 No
brand_unavailable 403 After the brand is restored
endpoint_shared 403 No
idempotency_key_required 400 After correction
idempotency_key_too_long 400 After correction
idempotency_key_in_flight 409 Yes
idempotency_key_reused 409 No, not with this key
brand_required 422 After correction
brand_not_found 422 After correction
publication_not_publishable 422 After correction
media_not_acceptable 422 No, not with this file
transition_not_allowed 409 No
endpoint_suspended 409 After reactivation
not_found 404 No
method_not_allowed 405 No
too_many_requests 429 Yes, after a delay
request_failed any other status 4xx: no; 5xx: yes
(validation, no code) 422 After correction
(outage, no code) 5xx Yes

API codes

unauthenticated — 401

Credentials missing, unreadable, unknown, wrong, or client revoked. Check that the qsc_… identifier is sent as the username and the qss_… secret as the password. See Authentication.

insufficient_scope — 403

The client is authenticated but lacks the scope required by the route. error.required_ability names the scope to have granted. GET /me lists all the ones you have at once.

plan_required — 403

The client is valid, but the plan of its workspace does not include the API (Free and Solo). The key is kept: it works again as soon as the workspace moves to Studio or above.

workspace_suspended — 403

The client's workspace is suspended by the Publisher, who sent the reason to its owner. The key is kept: it works again once the suspension is lifted. Nothing was executed or counted.

account_pending_deletion — 403

The owner of the client's workspace has asked for their account to be deleted. The workspace no longer acts: neither through the API, nor through the MCP server, nor through its webhooks, which stop being sent. The request cannot be cancelled from the product, and the keys will go with the workspace. Nothing was executed or counted.

brand_unavailable — 403

The client is restricted to a brand that is in the trash. It no longer reads or writes anything, not even what belonged to that brand: the key is kept, and works again if the brand is restored. A brand deleted permanently takes its keys with it. Nothing was executed or counted.

endpoint_shared — 403

PATCH, DELETE or POST …/test on an endpoint that covers the whole workspace, sent by a client restricted to a brand. Such a client lists these endpoints but does not change, delete or test them: a workspace client or the dashboard does. Nothing was changed or sent. See Webhooks.

idempotency_key_required and idempotency_key_too_long — 400

POST /publications or POST /media without an Idempotency-Key header, or with a key longer than 255 characters. Nothing was executed. See Idempotency.

idempotency_key_in_flight — 409

Another request carrying the same key is in progress. Wait one to a few seconds, then send the same request with the same key again: you will receive the response to the first one, or this conflict if it has not finished. A reservation whose process has disappeared is taken over after five minutes.

idempotency_key_reused — 409

The key has already been used, for this client, with a different body. Two cases:

  1. You changed the content while keeping the key: change the key along with the content (article-42-publie-v2).
  2. You believe you are sending the same content. Look for what varies from one send to the next: a recomputed timestamp, a field present one time out of two, destination_ids in a changing order, a regenerated image.

brand_required and brand_not_found — 422

The client covers the whole workspace and the write does not say which brand to target (brand_required), or designates a brand that is not in its workspace (brand_not_found). See Scopes.

publication_not_publishable — 422

The body is well formed, but the publication cannot be created. Nothing is written.

{
  "error": {
    "code": "publication_not_publishable",
    "message": "The publication date must be in the future.",
    "errors": ["The publication date must be in the future."],
    "destination_errors": {
      "dst_01k4b8x4s1t9j5q7v8y0z2b4d6": ["“Instagram Fabrique” requires an image."]
    }
  }
}

General errors, in errors:

Message Cause
Destination “dst_…” does not belong to this brand. This identifier designates no destination of the brand: it does not exist, or it belongs to another brand. Both cases receive the same message, in the same place.
File “med_…” is not available for this brand. This identifier designates no usable media item of the brand: unknown, from another brand, deleted — even if still in the trash —, or not ready yet.
A publication must carry a text or an image. No destination would receive either text or an image.
Choose a publication date. mode: "scheduled" without scheduled_at.
The publication date must be in the future. scheduled_at is in the past, to the second — including in draft or approval mode, where it is not even saved.
This brand has reached its monthly publication quota. The quota is used up until the first of the following month.

As long as a named destination or media item does not belong to the brand, no destination is examined: fix the identifiers first.

Destination errors, in destination_errors, keyed by identifier:

Message Cause
The connection of “X” must be restored before publishing. Destination disabled, token expired or connection to restore. An action in the dashboard is required.
“X” would receive neither text nor image. This network's overrides remove all its content.
“X” accepts at most N characters; this text has M. Text too long for this network; the message ends with , hashtags included when tags are added to it. Shorten it there only with overrides.
Instagram accepts at most 30 hashtags, those of the text and the tags combined. Too many hashtags in the Instagram caption.
Threads publishes the first tag as a topic, and a topic has at most 50 characters. First tag too long for a Threads topic.
“X” does not publish a first comment. first_comment as an override: no network publishes it today.
“X” requires an image. Instagram or Pinterest without an image.
“X” accepts at most N media. Too many images for this network.
“X” accepts alternative text of at most 500 characters. Alt text too long for Pinterest.

Fix, then send again with the same idempotency key: the failure released it.

media_not_acceptable — 422

The file cannot become a media item; it never touched the disk. error.errors lists the reasons. Convert the image, reduce it, then send the new file with a new key: its content has changed. See Media.

transition_not_allowed — 409

The body is valid; it is the state of the publication that prevents the requested action.

Message Route
This publication is awaiting approval: a reviewer must approve it before it goes out. publish
This publication is already scheduled. To change when it goes out, move it in the calendar; to stop it, cancel it. publish
This publication has already gone out: it can no longer be published. publish
This publication has no destination: add one before publishing it. publish
The publication date must be in the future. publish
This publication needs N delivery(ies) and only M remain this month. publish
This publication is finished: there is nothing left to cancel. cancel
No destination of this publication can be retried. retry
First restore the connection of “X”: the retry would fail immediately. retry

Read the publication again with GET /publications/{id} before deciding: a transition refusal is often proof that the action has already happened.

endpoint_suspended — 409

POST /webhooks/{id}/test to a suspended endpoint: it receives nothing, and announcing a test as sent would be a lie. Reactivate the endpoint from the dashboard, then test again. See Webhooks.

Framework codes

not_found — 404

The identifier does not exist, or the resource belongs to another brand or another workspace. The two cases are deliberately indistinguishable.

method_not_allowed — 405

The path exists, but not with this verb. Webhook endpoints are updated with PATCH, not PUT.

too_many_requests — 429

The rate limit has been exceeded — that of your address, that of your client, or that of a webhook endpoint's tests. See Limits and conventions. Wait for the delay given in the Retry-After header. Nothing was executed, and the idempotency key was not reserved: send the same request again with the same key.

request_failed

Any other HTTP error raised by the framework, whatever its status: another 4xx, or a 5xx such as 503 during maintenance. Retry a 5xx after a delay, not a 4xx.

Outage — 5xx

{ "message": "Server Error" }

Retry with increasing backoff and the same idempotency key: an error response releases the key, and the replay will run normally. This is precisely the case the key exists for: you do not know whether the write took place, the key does. Cap the number of attempts.