Start here

Keys, errors and limits

What every Mira API shares: how keys work, the sandbox, the response envelope, errors and limits.

In short

Send your key as a bearer token on every request; one key covers every API your account can use.
Act on the error code, never the message. Every API shares the same envelope and common errors.
Each key can make 500 requests a minute; new fields and events can appear at any time, breaking changes never come without a new version.

Developer keys

Send your company's key on every request as Authorization: Bearer ms_live_.... One key covers every API your account can use. The company owner creates, rotates and sets an expiry for keys in Mira Business under Settings, API Keys. Rotating stops the old key at once; there is no overlap, so update your system first.

A key belongs to one company, and everything it reads or changes is that company's own. Keep keys on your server: anyone holding one can act for your company.

What your account can use

What a key opens follows your kind of account. When Mira adds an API for your kind of account, your existing key can use it straight away.

API	Permissions	Dealer	Broker	Product seller
Journeys API	JOURNEYS_READ, JOURNEYS_WRITE	Yes	Yes
Vehicle stock API	VEHICLES_READ, VEHICLES_WRITE	Yes
Product catalogue API	PRODUCTS_READ, PRODUCTS_WRITE			Yes

Sandbox

Sandbox keys start with ms_test_. They run the same checks as live keys and never touch real data:

Journeys run against simulated customers and move on by themselves; you can force any outcome.
Vehicle stock and product catalogue calls are fully checked and answer with what would happen (WOULD_ADD or WOULD_UPDATE), and nothing is saved.
Live and sandbox data never mix: a live key cannot see sandbox records, and the other way round.

Retries and idempotency

Starting a journey needs an Idempotency-Key header, so a retry after a timeout never starts a second one. Stock and catalogue calls are naturally safe to retry: they are keyed by your own stock code or product code, so sending the same vehicle or product twice leaves one record with the latest details.

Responses

Every answer uses the same envelope: success, data, message and, on failure, errors. Act on errors[0].code, which never changes; messages are written for people and may be reworded.

Error

{
  "success": false,
  "data": null,
  "message": "Identity verification is not set up for this company. Configure it in Mira Business first.",
  "errors": [{ "field": "journey", "code": "EKYC_NOT_CONFIGURED", "message": "..." }]
}

Errors

These can come from any API. Each API's page lists its own errors too.

Status	Code	What to do
400	`VALIDATION_ERROR`	Something in the request needs fixing. The message says what, in plain words.
401	`INVALID_API_KEY`	The key is wrong, revoked, or not sent as Authorization: Bearer ms_live_... (or ms_test_...).
401	`API_KEY_EXPIRED`	The key has passed its expiry date. Rotate it in Mira Business.
403	`API_KEY_NOT_PERMITTED`	Your account type cannot use this API, or the key may not call this endpoint.
403	`IP_NOT_ALLOWED`	The key only accepts calls from listed IP addresses.
404	`NOT_FOUND`	No such record for this key. Live keys never see test data, and the other way round.
429	`RATE_LIMITED`	More than 500 requests in a minute on this key. Wait for the Retry-After seconds.
503	`TEMPORARILY_UNAVAILABLE`	The key could not be checked or a service is busy. Retry; nothing was changed.

Rate limits

500 requests a minute per key, across every API it uses. Beyond that, 429 with a Retry-After header.
Batch calls take up to 100 records and count as one request.
List pages return up to 100 records.

Versioning

Each API carries a version (every event has apiVersion). New fields and new event types can appear at any time, so ignore anything you do not recognise. Anything that would break an integration comes as a new version, announced in the changelog well in advance.