> For the complete documentation index, see [llms.txt](https://kevins-organization-58.gitbook.io/smtp-ghost-api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://kevins-organization-58.gitbook.io/smtp-ghost-api/error-handling.md).

# Error Handling

All error responses use JSON with an `"error"` or `"message"` field and the appropriate HTTP status code.

### Common HTTP Status Codes

| Status Code | Meaning                                              |
| ----------- | ---------------------------------------------------- |
| **400**     | Bad Request – missing or malformed input.            |
| **401**     | Unauthorized – missing or invalid API key.           |
| **402**     | Payment Required – insufficient credits.             |
| **404**     | Not Found – resource or endpoint does not exist.     |
| **422**     | Unprocessable Entity – validation failed.            |
| **500**     | Internal Server Error – unexpected server exception. |

### Error Response Format

```json
{
  "error": "Descriptive error message here."
}

```

Or for validation failures:

```json
{
  "status": "unprocessable",
  "message": "Unable to extract name or domain.",
  "profile": { /* partial profile data */ }
}

```

### Examples

#### 400 Bad Request

```bash
bashCopyEditcurl -X POST https://smtpghost.com/api/v1/linkedin_finder \
  -H "Content-Type: application/json" \
  -d '{}'
```

```json
{
  "error": "Please provide a LinkedIn URL."
}
```

#### 401 Unauthorized

```bash
curl -X POST https://smtpghost.com/api/v1/linkedin_finder \
  -H "Content-Type: application/json" \
  -H "X-KEY: WRONG_KEY" \
  -d '{ "linkedin_url": "…" }'
```

```json
{
  "error": "Unauthorized: Invalid API Key or Organization not found"
}
```

#### 402 Payment Required

```json
{
  "error": "Insufficient credits. You need 1 credits to perform LinkedIn email finder."
}
```

#### 422 Unprocessable Entity

```json
{
  "status": "unprocessable",
  "message": "Unable to extract name or domain.",
  "profile": { /* partial profile data */ }
}
```

#### 500 Internal Server Error

```json
{
  "error": "An internal error occurred: Connection timed out"
}
```