Skip to main content
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.

​
Status codes

StatusMeaningWhat to do
200 OKRequest succeeded.—
201 CreatedResource created.Read the new resource from data.
400 Bad RequestMalformed request or invalid body.Check field names, types, and required fields.
401 UnauthorizedMissing or invalid credentials.Verify your x-metal-client-id and x-metal-api-key headers.
403 ForbiddenAuthenticated but not allowed.Your key lacks permission for this resource or route.
404 Not FoundResource does not exist in your organization.Confirm the id and that it belongs to your org.
422 Unprocessable EntityRequest understood but cannot be processed (for example, a plan limit).Resolve the limit or conflict described in the body.
429 Too Many RequestsRate limit exceeded.Back off and retry. See Rate limits.
500 Internal Server ErrorSomething 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.