Errors

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:

{ "data": { "id": "665f1c2a9b1e4a0012a3b4c5", "canonicalName": "Acme Industrials" } }

Errors return a JSON body with an error message:

{ "error": "invalid api key or clientId" }

Some validation errors return additional detail describing the offending field. Endpoints that also check your role return a different body with code, message, and details fields. See Admin-only endpoints.

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.	The caller’s key or role 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.
`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.

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()

When contacting 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.

Core tasks

API essentials

Response format

Status codes

Handling errors

​Response format

​Status codes

​Handling errors

Response format

Status codes

Handling errors