Errors

Every Nylon endpoint answers a failure with the same envelope:

{
  "error": {
    "code": "invalid_request",
    "message": "This post is not valid for every profile you addressed.",
    "details": [
      {
        "network": "instagram",
        "code": "invalid_request",
        "message": "Instagram requires at least 1 media item — text-only posts are not supported."
      }
    ]
  }
}

code is the stable identifier to branch on. message is written for a human debugging an integration and may change at any time — never match on it. details is present when the failure has a per-field or per-network breakdown.

Codes

Code	Status	Meaning
`invalid_request`	400	The body, query or content breaks a rule. Check `details`.
`unauthorized`	401	The API key is missing, malformed or revoked.
`payment_required`	402	Billing is blocking the action. Usually an addressed profile is suspended: beyond the free allowance while the subscription is inactive. It is still connected and still listed with `suspended: true`.
`forbidden`	403	The credentials for a profile stopped working. The customer has to reconnect it in Nylon.
`not_found`	404	No such post or profile on this account.
`conflict`	409	The resource is not in a state that allows this — editing a post that is publishing, retrying one where everything succeeded.
`unsupported`	422	The network cannot do what was asked. Boards on a non-Pinterest profile, a Reel on a network without them.
`publish_failed`	422	The network rejected the post, or was unreachable. `details` names which network.
`rate_limited`	429	Too many requests for this API key.
`internal_error`	500	Something failed on our side.

Per-network failures

A post addressed to several profiles is validated against every one of them before anything is sent. If it is invalid anywhere, nothing publishes and details lists one entry per network:

{
  "error": {
    "code": "invalid_request",
    "message": "This post is not valid for every profile you addressed.",
    "details": [
      { "network": "instagram", "code": "invalid_request", "message": "Instagram requires at least 1 media item — text-only posts are not supported." },
      { "network": "youtube", "code": "unsupported", "message": "YouTube does not support threads." }
    ]
  }
}

Inside details, code is a publishing code rather than a top-level one:

Detail code	Meaning
`invalid_request`	The content breaks one of that network’s rules — length, media count, a missing required option.
`unsupported`	The network cannot do this at all — threads on YouTube, a Reel where there are none.
`media_error`	The media could not be fetched, read or transcoded.
`reauthentication_required`	The network refused our credentials. The customer must reconnect the profile.
`rejected_by_network`	The network refused the content itself.
`network_error`	The network accepted the request and then failed. Retryable.
`timeout`	The network did not answer in time. Retryable.
`profile_unavailable`	The profile is disconnected, suspended, or not on this account.

Validate the same body against POST /v1/validate first and you get the same answer without publishing anything.

A failure after publishing has started is not an error response. The post is created, the request returns 201, and the post’s status is partially_published or failed with the reason on each target. Retry those targets with POST /v1/posts/{postId}/retry — targets that already published are never re-sent. For a scheduled post there is no request to inspect, which is what webhooks are for: post.failed and post.partially_published carry the same targets.

Rate limits

Limits are per API key, not per IP, so a key used from two regions still gets one bucket and two customers behind one cloud NAT do not share one.

Endpoints	Limit
Reads and most writes	120 requests / minute
`POST /v1/posts`, `POST /v1/posts/{postId}/retry`	30 requests / minute

Successful responses carry the current state:

RateLimit-Limit: 120
RateLimit-Remaining: 118
RateLimit-Reset: 47

A 429 carries those plus Retry-After, in seconds.

Recommended handling

Do not retry 400, 401, 402, 404 or 409 without changing the request.
Retry 429 after Retry-After, and 5xx with exponential backoff.
Send an idempotency_key on POST /v1/posts so a retry after a timeout returns the original post instead of publishing twice.
Log error.code and the HTTP status. Never log the API key.

Get started

Capabilities

Guides

Codes

Per-network failures

Rate limits

Recommended handling

​Codes

​Per-network failures

​Rate limits

​Recommended handling

Codes

Per-network failures

Rate limits

Recommended handling