# What do DunSocial API error codes mean?

> Errors return success: false with an error string. 400 is bad input, 401 a missing or invalid token, 403 a permission or workspace problem, 404 not found, 409 a conflict, 413 too large, 429 rate limited or the X cap, 500 unexpected & 503 a missing dependency. Retry 429 & 500 only.

Updated: 2026-10-05.

## The error shape

A failed request returns a JSON body with `success: false` & an `error` string:

```json
{
  "success": false,
  "error": "Not a member of this workspace"
}
```

Some service errors also include a `message` field. Read `error` first.

## The status codes

| Status | Meaning |
|--------|---------|
| 400 | Bad input, or a business rule failed, such as validation or a wrong status |
| 401 | Missing or invalid bearer token |
| 403 | Authenticated but not allowed: role, scope, suspended member or wrong workspace |
| 404 | Not found, or not visible to you |
| 409 | Conflict, such as a workspace slug already taken |
| 413 | Body too large |
| 429 | Rate limited, or the X monthly posting cap reached |
| 500 | Unexpected server error |
| 503 | A dependency isn't configured |

An unpaid workspace also returns a 402 with a `subscription_required` code & a billing URL, as the SDK documents.

## Which to retry

Retry 429 & an occasional 500, with exponential backoff & a small cap on attempts. Those can clear on their own.

Don't retry 400, 401, 403 or 404 unchanged. They're telling you something about the request, & repeating it only wastes calls.

## Fixing a 400

For validation failures, the `error` string usually names the field or rule. If a post is too long or a platform option is missing, run the validate route to see every issue at once.

A 404 on media usually means an asset id that doesn't exist in this workspace.

DunSocial's validate route is the quickest way to turn a vague 400 into a list of specific issues.

## 401 versus 403

A 401 means DunSocial doesn't know who you are: the token is missing, malformed or revoked. A 403 means it knows who you are but won't allow the action.

For a PAT, a 403 is often a missing scope, the wrong workspace in `X-Workspace-Id`, or a suspended membership. DunSocial's scope table shows which scope each route needs.

## 429 has two causes

A rate limit clears after a short wait. The X monthly cap doesn't, so check `GET /api/posts/x-cap-usage` before a batch to tell them apart.

DunSocial returns `X-RateLimit-*` headers on a rate-limit response, which a client can use to pace itself.

## Log usefully

Log the status, the `error` string & the route, but never the token. If you wrap the API, pass the original `error` through, since it's the most specific clue available.

DunSocial's SDK raises a `DunSocialError` carrying the status & code, so you don't have to parse the body by hand.

## Related guides

- [What rate limits does the DunSocial API have?](https://www.dunsocial.com/hub/dunsocial-api-and-sdk-guides/what-rate-limits-does-the-dunsocial-api-have.md)
- [What do the DunSocial CLI exit codes mean?](https://www.dunsocial.com/hub/dunsocial-cli-guides/what-do-the-dunsocial-cli-exit-codes-mean.md)
- [How to authenticate with the DunSocial API](https://www.dunsocial.com/hub/dunsocial-api-and-sdk-guides/how-to-authenticate-with-the-dunsocial-api.md)
- [What happens if a scheduled post fails?](https://www.dunsocial.com/hub/social-media-scheduler/what-happens-if-a-scheduled-post-fails.md)

## About this document

This is the Markdown representation of https://www.dunsocial.com/hub/dunsocial-api-and-sdk-guides/what-do-dunsocial-api-error-codes-mean. The HTML version of the same page is at the same URL. You can also request Markdown from any page by sending `Accept: text/markdown`.

Machine-readable summary of the whole site: https://www.dunsocial.com/llms.txt

## Company

- Product: DunSocial, https://www.dunsocial.com
- Legal entity: THISUX PRIVATE LIMITED, Chennai, Tamil Nadu, India
- Support: support@dunsocial.com
- Open the app: https://app.dunsocial.com/login