Reference
Errors
The codes the API and MCP server return when a request fails, and what to do about each one.
Every error code
#A failed request returns a code as well as an HTTP status, so your code can tell a bad key apart from a plan limit or a rate limit. Every API error links to its own entry on this page.
Authentication
Access & limits
Requests
Media
Platform & server
Authentication
- What happened
- The request didn't include an API key.
- What to do
- Send your key in the Authorization header as a Bearer token.
Response body
{
"error": {
"code": "missing_api_key",
"message": "The request didn't include an API key.",
"details": [],
"request_id": "req_8f14e45fceea167a",
"doc_url": "https://deploy.social/docs/api/errors#missing_api_key"
}
}- What happened
- We couldn't recognize this API key.
- What to do
- Copy the whole key from Deploy and try again.
Response body
{
"error": {
"code": "invalid_api_key",
"message": "We couldn't recognize this API key.",
"details": [],
"request_id": "req_8f14e45fceea167a",
"doc_url": "https://deploy.social/docs/api/errors#invalid_api_key"
}
}- What happened
- This key has been revoked.
- What to do
- Create a new key in Deploy and update your client.
Response body
{
"error": {
"code": "api_key_revoked",
"message": "This key has been revoked.",
"details": [],
"request_id": "req_8f14e45fceea167a",
"doc_url": "https://deploy.social/docs/api/errors#api_key_revoked"
}
}- What happened
- This key has expired.
- What to do
- Create a new key in Deploy and update your client.
Response body
{
"error": {
"code": "api_key_expired",
"message": "This key has expired.",
"details": [],
"request_id": "req_8f14e45fceea167a",
"doc_url": "https://deploy.social/docs/api/errors#api_key_expired"
}
}- What happened
- The MCP request didn't include a connection or API key.
- What to do
- Connect your MCP app to Deploy, or send an API key as a Bearer token.
Response body
{
"error": {
"code": "missing_credentials",
"message": "The MCP request didn't include a connection or API key.",
"details": [],
"request_id": "req_8f14e45fceea167a",
"doc_url": "https://deploy.social/docs/api/errors#missing_credentials"
}
}- What happened
- The MCP connection token isn't valid or has expired.
- What to do
- Refresh the token, or connect the app to Deploy again.
Response body
{
"error": {
"code": "invalid_token",
"message": "The MCP connection token isn't valid or has expired.",
"details": [],
"request_id": "req_8f14e45fceea167a",
"doc_url": "https://deploy.social/docs/api/errors#invalid_token"
}
}- What happened
- This MCP connection was removed or lost access.
- What to do
- Connect the app to Deploy again.
Response body
{
"error": {
"code": "token_revoked",
"message": "This MCP connection was removed or lost access.",
"details": [],
"request_id": "req_8f14e45fceea167a",
"doc_url": "https://deploy.social/docs/api/errors#token_revoked"
}
}- What happened
- This credential can read, but this request needs write access.
- What to do
- Use a credential with write access, then try again.
Response body
{
"error": {
"code": "insufficient_scope",
"message": "This credential can read, but this request needs write access.",
"details": [],
"request_id": "req_8f14e45fceea167a",
"doc_url": "https://deploy.social/docs/api/errors#insufficient_scope"
}
}Access & limits
- What happened
- The workspace's plan doesn't include the API.
- What to do
- Upgrade in Deploy, then try again with the same key or connection.
Response body
{
"error": {
"code": "plan_required",
"message": "The workspace's plan doesn't include the API.",
"details": [],
"request_id": "req_8f14e45fceea167a",
"doc_url": "https://deploy.social/docs/api/errors#plan_required"
}
}- What happened
- The plan's videos for this month have all been posted.
- What to do
- Wait for the reset date in the message, or upgrade in Deploy.
Response body
{
"error": {
"code": "usage_limit_exceeded",
"message": "The plan's videos for this month have all been posted.",
"details": [],
"request_id": "req_8f14e45fceea167a",
"doc_url": "https://deploy.social/docs/api/errors#usage_limit_exceeded"
}
}- What happened
- The person who created this key no longer has access to the workspace.
- What to do
- Ask someone with workspace access to create a new key.
Response body
{
"error": {
"code": "access_revoked",
"message": "The person who created this key no longer has access to the workspace.",
"details": [],
"request_id": "req_8f14e45fceea167a",
"doc_url": "https://deploy.social/docs/api/errors#access_revoked"
}
}- What happened
- The key's workspace is archived.
- What to do
- Use a key from an active workspace.
Response body
{
"error": {
"code": "workspace_archived",
"message": "The key's workspace is archived.",
"details": [],
"request_id": "req_8f14e45fceea167a",
"doc_url": "https://deploy.social/docs/api/errors#workspace_archived"
}
}- What happened
- This credential reached a per-minute request limit or the plan's daily API post limit, or the workspace has as many link imports running as it can.
- What to do
- Wait the seconds in Retry-After, then try again. A daily_post_limit detail means the day's API posts are used up until midnight UTC. An imports_in_flight detail means an import has to finish first.
Response body
{
"error": {
"code": "rate_limited",
"message": "The Standard plan posts up to 30 videos a day through the API in your account, and today's are used. It resets at midnight UTC (2026-10-02T00:00:00.000Z). Posts made in the app don't count.",
"details": [
{
"path": "",
"code": "daily_post_limit",
"message": "The Standard plan posts up to 30 videos a day through the API in your account, and today's are used. It resets at midnight UTC (2026-10-02T00:00:00.000Z). Posts made in the app don't count."
}
],
"request_id": "req_8f14e45fceea167a",
"doc_url": "https://deploy.social/docs/api/errors#rate_limited"
}
}Requests
- What happened
- We couldn't read this request or one of its headers.
- What to do
- Check the JSON body and headers, then send it again.
Response body
{
"error": {
"code": "invalid_request",
"message": "We couldn't read this request or one of its headers.",
"details": [],
"request_id": "req_8f14e45fceea167a",
"doc_url": "https://deploy.social/docs/api/errors#invalid_request"
}
}- What happened
- One or more fields need fixing.
- What to do
- Read the details for the field paths and fixes, then send the request again.
Response body
{
"error": {
"code": "validation_failed",
"message": "One or more fields need fixing.",
"details": [
{
"path": "destinations[0].options.privacy",
"code": "required",
"message": "destinations[0].options.privacy is required."
}
],
"request_id": "req_8f14e45fceea167a",
"doc_url": "https://deploy.social/docs/api/errors#validation_failed"
}
}- What happened
- This Idempotency-Key was used for a different request.
- What to do
- Use a new key for a new request, or resend the original request unchanged.
Response body
{
"error": {
"code": "idempotency_key_reused",
"message": "This Idempotency-Key was used for a different request.",
"details": [],
"request_id": "req_8f14e45fceea167a",
"doc_url": "https://deploy.social/docs/api/errors#idempotency_key_reused"
}
}- What happened
- A request using this Idempotency-Key is still running.
- What to do
- Wait briefly and retry with the same key.
Response body
{
"error": {
"code": "idempotency_key_in_progress",
"message": "A request using this Idempotency-Key is still running.",
"details": [],
"request_id": "req_8f14e45fceea167a",
"doc_url": "https://deploy.social/docs/api/errors#idempotency_key_in_progress"
}
}- What happened
- There's nothing with that id in this workspace, or no endpoint at that path.
- What to do
- Check the id, the path, and which workspace your key or connection belongs to.
Response body
{
"error": {
"code": "not_found",
"message": "There's nothing with that id in this workspace, or no endpoint at that path.",
"details": [],
"request_id": "req_8f14e45fceea167a",
"doc_url": "https://deploy.social/docs/api/errors#not_found"
}
}- What happened
- This endpoint doesn't take that HTTP method.
- What to do
- Use a method from the Allow header, or check the endpoint in the API reference.
Response body
{
"error": {
"code": "method_not_allowed",
"message": "This endpoint doesn't take that HTTP method.",
"details": [],
"request_id": "req_8f14e45fceea167a",
"doc_url": "https://deploy.social/docs/api/errors#method_not_allowed"
}
}- What happened
- This post or destination can't take that action in its current state.
- What to do
- Read its current status, then choose an action it allows.
Response body
{
"error": {
"code": "invalid_state",
"message": "This post or destination can't take that action in its current state.",
"details": [],
"request_id": "req_8f14e45fceea167a",
"doc_url": "https://deploy.social/docs/api/errors#invalid_state"
}
}Media
- What happened
- The video is still processing.
- What to do
- Wait the time in Retry-After, check the video again, then retry.
Response body
{
"error": {
"code": "media_not_ready",
"message": "The video is still processing.",
"details": [],
"request_id": "req_8f14e45fceea167a",
"doc_url": "https://deploy.social/docs/api/errors#media_not_ready"
}
}Platform & server
- What happened
- Something broke on our side.
- What to do
- Retry. If it keeps happening, contact us with the request id.
Response body
{
"error": {
"code": "internal_error",
"message": "Something broke on our side.",
"details": [],
"request_id": "req_8f14e45fceea167a",
"doc_url": "https://deploy.social/docs/api/errors#internal_error"
}
}- What happened
- A connected platform didn't answer as expected.
- What to do
- Try again shortly. If it keeps happening, check the destination in Deploy.
Response body
{
"error": {
"code": "platform_error",
"message": "A connected platform didn't answer as expected.",
"details": [],
"request_id": "req_8f14e45fceea167a",
"doc_url": "https://deploy.social/docs/api/errors#platform_error"
}
}Detail codes
#Some errors carry details that point at the exact problem, such as a caption that runs too long for one destination or the day's post limit being reached.
requiredinvalid_valuetoo_longunknown_optionunsupported_fieldduplicate_destinationmedia_failedmedia_incompatiblemedia_expiredoption_conflicttimezone_requiredschedule_out_of_rangedaily_post_limitimports_in_flight