Errors - Orbbit Developer Docs

Every error, on every endpoint, has the same shape: a status code and a JSON body with an error object. For example, asking for a series that doesn’t exist:

curl --request GET \
  --url 'https://api.orbbit.co/v1/commodities/prices?series=butter-spot' \
  --header 'authorization: Bearer YOUR_API_KEY'

400 — unknown series

{
  "error": {
    "type": "invalid_request",
    "message": "Unknown series: butter-spot"
  }
}

Field	Type	Description
`error.type`	string	A stable, machine-readable name for the kind of error. Branch on this.
`error.message`	string	A human-readable explanation. Log it, show it to a developer — but don’t parse it, since the wording can change.

Error types

Status	`error.type`	What happened	What to do
`400`	`invalid_request`	A parameter is missing, the wrong type, or out of range.	Fix the request. The message names the parameter.
`401`	`unauthorized`	The API key is missing, malformed, unknown, or revoked.	Send `Authorization: Bearer <key>` with a live key.
`403`	`forbidden`	The key is valid but lacks this endpoint’s scope.	Add the scope in the console. See Authentication.
`404`	`not_found`	No record has the ID in the path.	Check the ID came from a search result.
`5xx`	`internal`	Something went wrong on Orbbit’s side. The message is always `An unexpected error occurred`.	Retry with exponential backoff. If it persists, contact support.

Common 400 errors

Endpoint	Message	Cause
`GET /v1/commodities/prices`	`Unknown series: <slug>`	A slug in `series` is not in the catalog. Get valid slugs from `GET /v1/commodities`.
`GET /v1/commodities/prices`	—	`series` is missing, has more than 100 slugs, a date is not a real `YYYY-MM-DD` day, or `from` is later than `to`.
`GET /v1/branded-foods`	`at most 200 per page`	`limit` is above 200.
Any endpoint with `limit`	—	`limit` is not a whole number of at least 1.

Retrying

Retry only 5xx errors. Every other error will fail again until you change the request. Every endpoint only reads data, so retrying a request never changes anything.

Python

import random, time, requests

def get_with_retry(url, headers, params=None, attempts=5):
    for attempt in range(attempts):
        response = requests.get(url, headers=headers, params=params)
        if response.status_code < 500:
            return response
        time.sleep(min(2 ** attempt, 30) + random.random())
    return response