Errors

Errors use standard HTTP status codes and return a JSON body:

{
  "statusCode": 404,
  "code": "UNKNOWN_STATE",
  "message": "Unknown state code XX"
}

Field	Meaning
statusCode	The HTTP status, repeated in the body
code	A stable identifier you can test for in code. Not every error has one
message	An explanation for a person. The wording may change, so do not match on it

Status codes

Status	Meaning	What to do
400	The request was wrong	Fix the parameter named in the message
401	The key is missing, wrong, expired or revoked	Check the key. See Authentication
403	The key is valid but may not read that data	Use a key with the right scope
404	Nothing exists for that state or month	Check the state code or the month
429	A limit was reached	Wait, as described below
5xx	Something went wrong on our side	Try again later. If it continues, tell us

Error codes

Code	Status	When
INVALID_PERIOD	400	period is not in the form YYYY-MM
FORECAST_PERIOD	400	A forecast month was passed to a risk endpoint. Use a forecast endpoint
INVALID_MONTHS	400	months is not a whole number from 1 to 4
SCOPE_REQUIRED	403	The key does not include the scope the endpoint needs
UNKNOWN_STATE	404	state is not one of the 37 state codes
PERIOD_NOT_AVAILABLE	404	period is outside the months the data covers
RATE_LIMITED	429	Too many requests this minute. Wait for the seconds in Retry-After
QUOTA_EXCEEDED	429	The monthly allowance is used up

401 responses have no code:

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Invalid, expired or revoked API key"
}

Retrying

Retry only when it can help:

Situation	Retry?
429 with RATE_LIMITED	Yes, after the seconds in Retry-After
5xx, or the connection failed	Yes, a few times, waiting longer each time
429 with QUOTA_EXCEEDED	No. Wait until the month ends
400, 401, 403, 404	No. The same request will fail the same way

In the Python SDK

Each status has its own exception, all subclasses of AI4MError, with status_code and code attributes. See Python SDK.