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

# Errors

> HTTP status codes, error response format, and how to handle API errors.

The API uses standard HTTP status codes and returns errors in a consistent JSON format.

## Error format

All errors return a JSON body with a `message` field:

```json theme={null}
{
  "message": "Error message describing what went wrong"
}
```

Validation errors include additional detail:

```json theme={null}
{
  "message": "Validation failed",
  "errors": [
    { "field": "tool", "message": "Required", "code": "invalid_type" }
  ]
}
```

## Status codes

### Client errors (4xx)

| Status | Name              | When it happens                                              |
| ------ | ----------------- | ------------------------------------------------------------ |
| 400    | Bad Request       | Invalid JSON, missing fields, invalid values, unknown fields |
| 401    | Unauthorized      | Missing or invalid API key                                   |
| 402    | Payment Required  | Not enough credits                                           |
| 403    | Forbidden         | Trying to access another user's resource                     |
| 404    | Not Found         | Invalid endpoint, tool, model, or generation ID              |
| 429    | Too Many Requests | Rate limit exceeded                                          |

### Server errors (5xx)

| Status | Name                  | What to do                               |
| ------ | --------------------- | ---------------------------------------- |
| 500    | Internal Server Error | Retry after a few seconds                |
| 502    | Bad Gateway           | Retry after a few seconds                |
| 503    | Service Unavailable   | Service is temporarily down, retry later |

## Handling errors

<CodeGroup>
  ```javascript JavaScript theme={null}
  const generate = async (tool, input) => {
    const response = await fetch('https://api.artificialstudio.ai/api/run', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': 'YOUR_API_KEY'
      },
      body: JSON.stringify({ tool, input })
    });

    if (!response.ok) {
      const error = await response.json();

      switch (response.status) {
        case 401:
          throw new Error('Invalid API key');
        case 402:
          throw new Error('Insufficient credits');
        case 429:
          throw new Error('Rate limit exceeded. Retry later.');
        default:
          throw new Error(error.message || 'Request failed');
      }
    }

    return response.json();
  };
  ```

  ```python Python theme={null}
  import requests

  def generate(tool, input):
      response = requests.post(
          'https://api.artificialstudio.ai/api/run',
          headers={
              'Content-Type': 'application/json',
              'Authorization': 'YOUR_API_KEY'
          },
          json={'tool': tool, 'input': input}
      )

      if response.status_code == 401:
          raise Exception('Invalid API key')
      elif response.status_code == 402:
          raise Exception('Insufficient credits')
      elif response.status_code == 429:
          raise Exception('Rate limit exceeded. Retry later.')
      elif not response.ok:
          error = response.json()
          raise Exception(error.get('message', 'Request failed'))

      return response.json()
  ```
</CodeGroup>

## Common errors and solutions

### Invalid API key (401)

```json theme={null}
{ "message": "Authorization header is required" }
```

Check that your API key is correct and included in the `Authorization` header. Do not use the `Bearer` prefix.

### Insufficient credits (402)

```json theme={null}
{ "message": "You do not have enough credits to perform this action" }
```

Add credits at [Account Settings](https://app.artificialstudio.ai/account/settings).

### Tool not found (404)

```json theme={null}
{ "message": "Tool not found" }
```

Verify the tool slug. Use [`GET /api/tools`](/api/tools) to list available tools.

### Rate limit exceeded (429)

```json theme={null}
{ "message": "Too many API requests, please try again later" }
```

Wait before retrying. See [rate limits](/getting-started/authentication#rate-limits) for details on your plan's limits.

### Validation error (400)

```json theme={null}
{
  "message": "Validation failed",
  "errors": [
    { "field": "tool", "message": "Required", "code": "invalid_type" }
  ]
}
```

Check the required parameters for your tool. The API rejects unknown fields — only send documented parameters.