Reference
Errors
The single error format of the Socialit API, its error types and HTTP status codes, and how to handle network errors.
Updated Oct 14, 2026
Every error, from validation to a network refusing a post, uses one shape:
{
"error": {
"type": "invalid_request_error",
"code": "validation_failed",
"message": "The post cannot be published to X.",
"param": "content",
"errors": { "content": ["Too long for X (280)"] },
"platform": "x",
"platform_code": "186",
"doc_url": "https://socialit.com/docs/networks/x/"
},
"request_id": "req_4hQx…"
}| Field | Meaning |
|---|---|
type |
The category (table below). Branch on this first. |
code |
A stable, specific code such as validation_failed, invalid_api_key or plan_required. |
message |
A human-readable explanation. Don’t parse it. |
param |
The request field the error is about, when there is one. |
errors |
Field-by-field messages for validation errors. |
platform, platform_code |
The network and its own error code, when the network refused. |
request_id |
Include it when you contact support. |
Types
type |
Status | When |
|---|---|---|
invalid_request_error |
400, 422 | Malformed request or validation failed |
authentication_error |
401 | Missing, invalid or revoked credentials |
permission_error |
403 | The credential can’t do this, or can’t access this profile |
not_found_error |
404 | The object doesn’t exist or isn’t visible to you |
conflict_error |
409 | The request conflicts with the current state, or reused an idempotency key |
plan_limit_error |
402, 403 | Your plan doesn’t include this, or a limit was reached; includes usage and required_plan |
rate_limit_error |
429 | Too many requests; see Rate limits |
platform_error |
502 | The network returned an error |
api_error |
500 | Something went wrong on our side |
Handling them
4xxerrors won’t succeed if repeated unchanged. Fix the request first.- Retry
429,502and5xxwith exponential backoff, and use an idempotency key so retries are safe. 409 conflict_errorwith codeaccount_needs_reconnectmeans the account’s token was revoked: reconnect it (the error and theaccount.needs_reconnectwebhook carry the account).403 missing_scopeslistsmissing_scopesand areconnect_urlthat upgrades them.403 plan_limit_errorwithplan_requirednames therequired_plan;402 insufficient_creditsmeans prepaid X credits ran out. See Billing and usage.- Network-specific operations answer
409 capability_not_supported(or422 not_supported) when a network can’t do something, withplatformandcapability.