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

# Errors

> What to do when a call fails, and how to tell a real failure from a partial success.

## Quick fixes

| Status | What it means | What to do |
| - | - | - |
| `400` | Something in your request is wrong | Read `error`, fix the request |
| `401` | The API key is missing, wrong or revoked | Check the `Authorization` header |
| `402` | You have no LinkedIn URL credits left | See [Credits](https://docs.groovin.ai/reference/limits.md#credits) |
| `403` | Your account cannot do this | See [What your account needs](https://docs.groovin.ai/reference/authentication.md#what-your-account-needs) |
| `404` | It does not exist, LinkedIn is not connected, or the CRM contact has no LinkedIn URL | Check the id. Reconnect LinkedIn in Groovin. Add the URL in your CRM |
| `405` | You did not use `POST` | Every route uses `POST`, even the ones that read |
| `409` | Something is already running | Wait for it to finish |
| `410` | The import's data was deleted | Start a new import |
| `422` | The CRM contact's LinkedIn URL cannot be used | Fix the URL in your CRM |
| `429` | LinkedIn or your CRM is slowing you down | **Stop. Wait at least 5 minutes.** |
| `500` | Something failed on our side | Retry later. If it continues, contact support |
| `502` | LinkedIn or your CRM could not be reached | Retry later |
| `504` | No answer in time | **On a send, check first.** See below |

This list can grow: some statuses come straight from LinkedIn. A `401` or `403` can also be LinkedIn's answer, in which case `error` mentions LinkedIn.

## A send failed

> [!CAUTION]
>
> **After an error on a send, the message or invitation may already be gone.** Never retry automatically.

If `linkedin/messages` or `linkedin/invitations` answers a 5xx, a 429, or no answer at all (a network error, or a timeout in your tool):

1. **Wait a few minutes.** Groovin's copy of your inbox can lag behind LinkedIn.
2. **Check.** Read the conversation with [`linkedin/chat-messages`](https://docs.groovin.ai/reference/api/get-chat-messages). If you sent by profile and have no `conversation_id`, find it in [the conversation list](https://docs.groovin.ai/reference/api/list-conversation-attendees.md). For an invitation, check the [pending invitations](https://docs.groovin.ai/reference/api/list-pending-invitations.md).
3. **Only if it is still not there,** try again, once.

In a browser, a gateway timeout can show up as a network error rather than a 504. Treat it the same way.

## What an error looks like

Every failure answers with an HTTP status and one field:

```json theme={null}
{ "error": "Too many crm_contact_ids: max 25 per enable request (got 40). Split into smaller batches." }
```

> [!WARNING]
>
> There are no error codes, and the text can change. In your code, decide what to do from the HTTP status. Show the text to a person, or give it to your AI assistant.

On a `429` or a `5xx`, the text ends with advice on what to do next. On a send, that advice is to check before re-sending.

> [!WARNING]
>
> That advice can say "Re-sending is safe" when it is not. On [a connections import](https://docs.groovin.ai/reference/api/start-connections-import.md), [a domain lookup](https://docs.groovin.ai/reference/api/find-company-domains.md) or [a profile read](https://docs.groovin.ai/reference/api/get-profile.md), follow the page of that route instead.

## An HTTP 200 can hold failures

Routes that handle several items answer 200 even when some items failed. Always check each item:

```json theme={null}
{
  "total": 2,
  "succeeded": 1,
  "failed": 1,
  "results": [
    { "linkedin_profile_id": "ACoAA…", "crm_contact_id": "…", "error": null, "error_status": null },
    { "linkedin_profile_id": "ACoAA…", "crm_contact_id": null, "error": "…", "error_status": 429 }
  ],
  "retry_guidance": "…"
}
```

| Field | How to use it |
| - | - |
| `error` | What went wrong for this item |
| `error_status` | `429` or `5xx` means temporary. Anything else needs a fix |
| `retry_guidance` | When to retry, and which items |
| `not_processed` | Items the call did not reach. Send only these again |

This applies to [`crm/contacts`](https://docs.groovin.ai/reference/api/create-contacts), [`crm/contacts/sync-toggle`](https://docs.groovin.ai/reference/api/toggle-sync), [`crm/contacts/find-linkedin-url`](https://docs.groovin.ai/reference/api/find-linkedin-urls) and [`crm/companies/find-domains`](https://docs.groovin.ai/reference/api/find-company-domains).

## When is it safe to retry?

| Situation | Retry? |
| - | - |
| `400`, `401`, `403`, `404` | No. Fix the cause first |
| `429` | Yes, after at least 5 minutes. If the text mentions a monthly limit, wait for the reset |
| `5xx` on a read | Yes, after a pause. Live LinkedIn reads spend your allowance again |
| `5xx` on a batch | Yes, only the failed items |
| Any failure on a send | **Not before checking.** See [A send failed](#a-send-failed) |

Each page says what repeating that call does, and [What each call really does](https://docs.groovin.ai/reference/side-effects.md) lists them all.

There are no idempotency keys: Groovin cannot recognize a repeated request on your behalf.

## On the MCP

Your AI assistant gets these same messages, but as a tool result rather than an HTTP status. See [MCP errors](https://docs.groovin.ai/reference/mcp/errors.md).


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