> ## Documentation Index
> Fetch the complete documentation index at: https://docs.metal.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 failures.

The Metal API uses conventional HTTP status codes to signal success or failure. Codes in the `2xx` range indicate success, `4xx` indicate a problem with the request, and `5xx` indicate a server-side error.

## Response format

Successful responses wrap their payload in a `data` field:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{ "data": { "id": "665f1c2a9b1e4a0012a3b4c5", "canonicalName": "Acme Industrials" } }
```

Errors return a JSON body with an `error` message:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{ "error": "invalid api key or clientId" }
```

Some validation errors return additional detail describing the offending field.

## Status codes

| Status                      | Meaning                                                                 | What to do                                                     |
| --------------------------- | ----------------------------------------------------------------------- | -------------------------------------------------------------- |
| `200 OK`                    | Request succeeded.                                                      | Nothing.                                                       |
| `201 Created`               | Resource created.                                                       | Read the new resource from `data`.                             |
| `400 Bad Request`           | Malformed request or invalid body.                                      | Check field names, types, and required fields.                 |
| `401 Unauthorized`          | Missing or invalid credentials.                                         | Verify your `x-metal-client-id` and `x-metal-api-key` headers. |
| `403 Forbidden`             | Authenticated but not allowed.                                          | Your key lacks permission for this resource or route.          |
| `404 Not Found`             | Resource does not exist in your organization.                           | Confirm the `id` and that it belongs to your org.              |
| `422 Unprocessable Entity`  | Request understood but cannot be processed (for example, a plan limit). | Resolve the limit or conflict described in the body.           |
| `429 Too Many Requests`     | Rate limit exceeded.                                                    | Back off and retry. See [Rate limits](/guides/rate-limits).    |
| `500 Internal Server Error` | Something went wrong on Metal's side.                                   | Retry with backoff; contact support if it persists.            |

## Handling errors

Always check the status code before reading the body. Treat `429` and `5xx` as retryable with exponential backoff; treat `4xx` (other than `429`) as a problem to fix in your request.

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import time
import requests

def request_with_retry(method, url, headers, max_retries=5, **kwargs):
    for attempt in range(max_retries):
        res = requests.request(method, url, headers=headers, **kwargs)
        if res.status_code < 400:
            return res
        if res.status_code == 429 or res.status_code >= 500:
            time.sleep(2 ** attempt)  # exponential backoff
            continue
        # Non-retryable client error
        res.raise_for_status()
    res.raise_for_status()
```

<Tip>
  When contacting [support@metal.ai](mailto:support@metal.ai) about an error, include the request method, path, status code, and the full error body. This is the fastest way to get a resolution.
</Tip>


## Related topics

- [MCP tools reference](/mcp/tools-reference.md)
- [Authentication](/authentication.md)
- [Update a workflow](/api-reference/workflows/update-a-workflow.md)
- [Update a list](/api-reference/lists/update-a-list.md)
- [API reference](/api-reference/introduction.md)