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

# Errors

> The error shape every tool shares, the categories, and the LinkedIn error codes.

## A refused request

A refusal before payment is never charged. It has a non-2xx status:

```json theme={null}
{ "error": "account_send_limit", "message": "Daily LinkedIn message cap reached for this account", "details": { "resets_at": "2026-11-04T00:00:00.000Z" } }
```

Branch on `error`. `message` may change. `details` is optional.

`GET /v1/submissions/recover` answers `404 submission_not_found` with `acceptance: unknown` when it has no record of the key. [Timeouts and retries](https://docs.oneshotagent.com/sdk/timeouts-and-retries.md#recover-a-call) says when submitting with that key is safe.

## A failed job

[`GET /v1/requests/{request_id}`](https://docs.oneshotagent.com/api-reference/status) answers `200` with:

```json theme={null}
{
  "status": "failed",
  "error": "LinkedIn will not accept this action for this profile. Do not retry it for this person.",
  "error_code": "recipient_unavailable",
  "error_category": "validation",
  "error_status": 400,
  "result": { "reason": "LinkedIn will not accept this action for this profile. Do not retry it for this person.", "upstream_reason": "invalid_recipient" }
}
```

Branch on `error_code`. `error` may change. LinkedIn failures put `reason` in `result`, plus `upstream_reason`, LinkedIn's own error type, when it gave one. The TypeScript SDK throws a `JobError` with `code` and `partialResult`.

## Categories

| `error_category` | `error_status` | What to do |
| - | - | - |
| `payment` | 402 | Fix the wallet. |
| `validation` | 400 | Change the request. |
| `upstream` | 502 | Follow the code. |
| `internal` | 500 | Contact support. Do not retry blindly. |

Unlisted codes are `internal`. See also [job status](https://docs.oneshotagent.com/api-reference/status.md#error-codes).

## LinkedIn codes

For [invite](https://docs.oneshotagent.com/api-reference/linkedin/invite.md), [withdraw](https://docs.oneshotagent.com/api-reference/linkedin/withdraw.md), [message](https://docs.oneshotagent.com/api-reference/linkedin/message.md) and [reply](https://docs.oneshotagent.com/api-reference/linkedin/reply.md). Terminal: the same request cannot succeed. Retryable: it can, later.

| `error_code` | Meaning | Retry |
| - | - | - |
| `recipient_unavailable` | LinkedIn refuses this action for this profile | Terminal |
| `recipient_not_connected` | Not a first-degree connection | Terminal until they accept an invitation |
| `target_not_found` | No such profile or conversation | Terminal |
| `content_rejected` | LinkedIn refused the note or text | Terminal; change it |
| `request_rejected` | Refused for another reason; see `upstream_reason` | Terminal |
| `note_too_long` | Note over this account's limit | Terminal; shorten it |
| `note_limit_reached` | No notes left this month | Terminal; send without one |
| `email_required` | LinkedIn wants their email first | Terminal |
| `invitation_cancelled` | Withdrawn before sending | Terminal |
| `invitation_not_found` | Not an invitation on this account | Terminal |
| `use_original_invitation` | A duplicate; withdraw the original | Terminal |
| `grant_revoked` | The grant was revoked or changed | Terminal until granted again |
| `account_disconnected` | The session ended | Retryable after reconnect |
| `account_send_limit` | Daily cap reached | Retryable at UTC midnight |
| `rate_limited` | LinkedIn is limiting the account (invite, withdraw) | Retryable later |
| `service_unavailable` | LinkedIn unreachable; nothing sent | Retryable |
| `invitation_unverified` | Not found on LinkedIn; not withdrawn | Retryable later |
| `receipt_unavailable` | No receipt; nothing sent | Retryable |
| `send_unverified` | Never confirmed in 24 hours | Check LinkedIn; never resend blindly |

Retry with a new `Idempotency-Key`. The same key never sends again.

## Unconfirmed sends and refunds

A timeout, server error or throttled send may still have reached LinkedIn. The job stays `processing` with `send_status: "ambiguous"` while OneShot checks, then reports `send_unverified` after 24 hours. It is not refunded, unless a throttled invitation is shown not to have been sent.

A request that fails before reaching LinkedIn is refunded as account credit within a day; refunds run daily at 03:00 UTC. The receipt gets a new signed revision marked failed.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.