Skip to content
Docs

Reference

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:

JSON
{
  "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

  • 4xx errors won’t succeed if repeated unchanged. Fix the request first.
  • Retry 429, 502 and 5xx with exponential backoff, and use an idempotency key so retries are safe.
  • 409 conflict_error with code account_needs_reconnect means the account’s token was revoked: reconnect it (the error and the account.needs_reconnect webhook carry the account). 403 missing_scopes lists missing_scopes and a reconnect_url that upgrades them.
  • 403 plan_limit_error with plan_required names the required_plan; 402 insufficient_credits means prepaid X credits ran out. See Billing and usage.
  • Network-specific operations answer 409 capability_not_supported (or 422 not_supported) when a network can’t do something, with platform and capability.