> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nylon.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Retry failed targets

> Republish only the targets that failed, never one that already went out.



## OpenAPI

````yaml /openapi.yaml post /v1/posts/{postId}/retry
openapi: 3.1.0
info:
  title: Nylon API
  version: 1.0.0
  description: |
    One API for publishing to twelve social networks.

    You address a post to connected profile ids; Nylon knows which network each
    one belongs to, what that network accepts, and how to get the media there.
    Character limits, media specs, upload protocols and threading rules are
    normalised before the request reaches a platform, and every failure comes
    back in one error taxonomy.

    ## Conventions

    - Request and response fields are `snake_case`.
    - Successful responses wrap the payload in `data`. List responses add
      `meta.pagination`.
    - Failures return `{ "error": { "code", "message", "details?" } }`.
      Branch on `code`; `message` is written for humans and may change.
    - Times are ISO 8601 with a `Z` offset.
    - Successful responses carry `RateLimit-Limit`, `RateLimit-Remaining` and
      `RateLimit-Reset`. A `429` carries those plus `Retry-After`.
servers:
  - url: https://api.nylon.dev
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Posts
    description: Create, schedule, inspect, edit and retry posts.
  - name: Profiles
    description: Social profiles connected to the authenticated Nylon account.
  - name: Connections
    description: Start a connection and see which networks are available.
  - name: Networks
    description: What each network accepts, as data.
  - name: Validation
    description: Dry-run a post without publishing it.
  - name: Webhooks
    description: Endpoints Nylon calls when a post finishes or a profile stops working.
paths:
  /v1/posts/{postId}/retry:
    parameters:
      - $ref: '#/components/parameters/PostId'
    post:
      tags:
        - Posts
      summary: Retry failed targets
      description: |
        Republishes the targets that did not go out — what failed, and what a
        run that died mid-flight never reached.

        Targets that already published are never included, whatever
        `target_ids` asks for. Double-posting is the one failure a customer
        cannot undo, so it is refused here and again in the publisher. A target
        a cancellation skipped is left alone for the same reason.

        A post that has not been attempted yet cannot be retried: retrying a
        scheduled post would send it early rather than recover anything. Use
        `publish_now` on `PATCH /v1/posts/{postId}` for that.
      operationId: retryPost
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RetryPostRequest'
            examples:
              all:
                summary: Retry everything that failed
                value: {}
              some:
                summary: Retry two specific targets
                value:
                  target_ids:
                    - cly7q9v2m0002x8b3b5e6f0ee
                    - cly7q9v2m0003x8b3c7g8h0ff
      responses:
        '200':
          description: The post after the retry, with each target's new state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: |
            Nothing to retry: every target has published, or the post has not
            been attempted yet, or it was cancelled.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                nothingToRetry:
                  summary: Everything already published
                  value:
                    error:
                      code: conflict
                      message: >-
                        There is nothing to retry — every target on this post
                        has published.
                notAttempted:
                  summary: Still scheduled
                  value:
                    error:
                      code: conflict
                      message: >-
                        This post has not been published yet, so there is
                        nothing to retry. Send it now with `publish_now`, or
                        move `scheduled_at`.
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  parameters:
    PostId:
      name: postId
      in: path
      required: true
      description: The Nylon id of the post.
      schema:
        type: string
        example: cly7q9v2m0001x8b3a1c4d0dd
  schemas:
    RetryPostRequest:
      type: object
      properties:
        target_ids:
          type: array
          description: Retry only these targets. Defaults to every target that failed.
          items:
            type: string
    PostResponse:
      type: object
      required:
        - data
      properties:
        data:
          $ref: '#/components/schemas/Post'
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          $ref: '#/components/schemas/Error'
    Post:
      type: object
      required:
        - id
        - status
        - text
        - media
        - post_type
        - auto_thread
        - source
        - created_at
        - updated_at
        - targets
      properties:
        id:
          type: string
          example: cly7q9v2m0001x8b3a1c4d0dd
        status:
          type: string
          description: |
            Derived from the targets. `partially_published` means some
            networks took it and some did not — retry the rest.
          enum:
            - draft
            - scheduled
            - publishing
            - published
            - partially_published
            - failed
            - cancelled
          example: published
        text:
          type: string
        media:
          type: array
          items:
            $ref: '#/components/schemas/Media'
        link:
          oneOf:
            - $ref: '#/components/schemas/Link'
            - type: 'null'
        post_type:
          type: string
          enum:
            - post
            - reel
            - story
        title:
          type:
            - string
            - 'null'
        thread:
          type:
            - array
            - 'null'
          items:
            type: string
        auto_thread:
          type: boolean
        networks:
          type: object
          description: The per-network overrides this post was created with.
          additionalProperties: true
        scheduled_at:
          type:
            - string
            - 'null'
          format: date-time
        published_at:
          type:
            - string
            - 'null'
          format: date-time
        source:
          type: string
          description: Where the post came from.
          example: api
        idempotency_key:
          type:
            - string
            - 'null'
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        targets:
          type: array
          items:
            $ref: '#/components/schemas/PostTarget'
    Error:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          description: The stable identifier to branch on.
          enum:
            - invalid_request
            - unauthorized
            - payment_required
            - forbidden
            - not_found
            - conflict
            - rate_limited
            - unsupported
            - publish_failed
            - internal_error
          example: unauthorized
        message:
          type: string
          description: Written for humans. Do not match on it.
          example: A valid Nylon API key is required.
        details:
          type: array
          description: Present when the failure has a per-field or per-network breakdown.
          items:
            $ref: '#/components/schemas/ErrorDetail'
    Media:
      type: object
      required:
        - url
        - type
      properties:
        url:
          type: string
          format: uri
        type:
          type: string
          enum:
            - image
            - video
            - gif
          description: Resolved from the file, not from the extension.
        mime_type:
          type: string
          example: image/jpeg
        size_bytes:
          type:
            - integer
            - 'null'
          description: Null when the host refuses HEAD and sends no length.
        alt:
          type:
            - string
            - 'null'
        thumbnail_url:
          type:
            - string
            - 'null'
          format: uri
    Link:
      type: object
      required:
        - url
      properties:
        url:
          type: string
          format: uri
        title:
          type:
            - string
            - 'null'
        description:
          type:
            - string
            - 'null'
        image_url:
          type:
            - string
            - 'null'
          format: uri
    PostTarget:
      type: object
      description: One post, on one profile. A post's own status is derived from these.
      required:
        - id
        - profile_id
        - network
        - profile_name
        - status
        - post_ids
        - attempts
      properties:
        id:
          type: string
          example: cly7q9v2m0002x8b3b5e6f0ee
        profile_id:
          type: string
          example: cly7p2q4k0001x8b3f2n9d0aa
        network:
          $ref: '#/components/schemas/Network'
        profile_name:
          type: string
          description: The profile's name as it was when the post was created.
          example: Nylon Studio
        status:
          type: string
          enum:
            - pending
            - publishing
            - published
            - failed
            - skipped
          example: published
        post_ids:
          type: array
          description: >-
            The network's own ids for what was published. More than one when the
            post was threaded.
          items:
            type: string
          example:
            - '17924418112233445'
        url:
          type:
            - string
            - 'null'
          format: uri
          description: Permalink to the published post, where the network returns one.
        attempts:
          type: integer
          description: How many times publishing this target has been attempted.
          example: 1
        published_at:
          type:
            - string
            - 'null'
          format: date-time
        error:
          type:
            - object
            - 'null'
          description: Why this target failed. Null while pending or once published.
          properties:
            code:
              type: string
              example: rejected_by_network
            message:
              type: string
              example: The caption contains a link this account is not allowed to post.
    ErrorDetail:
      type: object
      required:
        - message
      properties:
        field:
          type: string
          description: The request field the problem is about.
          example: profile_ids
        network:
          type: string
          description: The network the problem is about.
          example: instagram
        code:
          type: string
          description: |
            Machine-readable identifier for this problem. On a per-network
            detail this is a publishing code: `invalid_request`,
            `unsupported`, `media_error`, `reauthentication_required`,
            `rejected_by_network`, `network_error`, `timeout`,
            `profile_unavailable` or `internal_error`.
          example: invalid_request
        message:
          type: string
          example: >-
            Instagram requires at least 1 media item — text-only posts are not
            supported.
    Network:
      type: string
      description: A network Nylon publishes to.
      enum:
        - facebook
        - instagram
        - x
        - linkedin
        - pinterest
        - bluesky
        - threads
        - tiktok
        - youtube
        - google_business
        - mastodon
        - discord
      example: instagram
  responses:
    Unauthorized:
      description: The bearer API key is missing, malformed or revoked.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            missingKey:
              value:
                error:
                  code: unauthorized
                  message: A valid Nylon API key is required.
    NotFound:
      description: No such resource on this account.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            missing:
              value:
                error:
                  code: not_found
                  message: Post could not be found.
    RateLimited:
      description: |
        Too many requests for this API key. Reads allow 120 requests a minute;
        publishing endpoints allow 30, because each one costs real upstream
        calls. The limit is per key, not per IP.
      headers:
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            throttled:
              value:
                error:
                  code: rate_limited
                  message: Too many requests. Retry after the window resets.
    InternalError:
      description: Nylon encountered an unexpected error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  headers:
    RetryAfter:
      description: Seconds to wait before retrying.
      schema:
        type: integer
        example: 47
    RateLimitLimit:
      description: Requests allowed in the current window.
      schema:
        type: integer
        example: 120
    RateLimitRemaining:
      description: Requests left in the current window.
      schema:
        type: integer
        example: 119
    RateLimitReset:
      description: Seconds until the window resets.
      schema:
        type: integer
        example: 47
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Nylon API key
      description: An API key beginning with `nylon_live_`.

````