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

# Errors

> Reference for Datamagnet API error codes and HTTP status responses, including authentication failures, rate limits, and validation errors.

# Errors

This guide covers what happens when something goes wrong while you work with the API, along with the status codes and error types you might encounter.

To tell if your request was successful, check the status code on the API response. If a response comes back unsuccessful, use the error type and error message to figure out what went wrong and debug before contacting support.

> [!NOTE]
>
> Before reaching out to support, double-check your code. Most reported errors turn out to be in the request itself rather than the API.

***

## Status codes

Here is a list of the different categories of status codes returned by the Datamagnet API. Use these to understand if a request was successful.

| Status Code | Description |
| - | - |
| **2xx** | A 2xx status code indicates a successful response. |
| **4xx** | A 4xx status code indicates a client error — something in your request needs to be corrected. |
| **5xx** | A 5xx status code indicates a server error on our side. These are rare. |

***

## Timeouts

Data is collected live when you request it, so response times vary: most calls answer in a few seconds, and a slow lookup can take longer. Every request is answered within about 80 seconds. A lookup that cannot finish in that time is returned as a failure you can retry (`"retryable": true` on company and person lookups, an error status on the other endpoints) and is **not charged**.

If your client gives up sooner, tell us how long it waits with the `X-Request-Timeout` header, in seconds:

```bash theme={null}
curl -X POST https://api.datamagnet.co/api/v1/post/reactions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Request-Timeout: 30" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.linkedin.com/feed/update/urn:li:activity:7430615551086850048"}'
```

We then answer a few seconds before your timeout: with the data, or with an uncharged retryable failure if it is not ready. Without the header, a request your client abandons can still complete and be charged.

***

## Error types

When a request is unsuccessful, the Datamagnet API returns an error response with an error type and message. Use this information to understand what went wrong and how to fix it. Most error messages are designed to be actionable.

The Datamagnet API uses two error types, listed below.

### Error response format

```json Error response theme={null}
{
  "type": "api_error",
  "message": "No way this is happening!?",
  "documentation_url": "https://docs.datamagnet.co/errors/api_error"
}
```

### Error types

| Error Type | Description |
| - | - |
| **api\_error** | Indicates an error on the Datamagnet side. These are rare. |
| **invalid\_request** | Indicates an error in your request, such as missing or malformed parameters. |


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