Errors and limits — IngevoraMirage

Errors and limitsThe error envelopeEvery error from the API has the same shape:

json

{
  "data": null,
  "success": false,
  "errorMessage": "Lens not found",
  "errorCode": 404
}

success is false, and data is null.

errorCode is the HTTP status, as a number.

errorMessage is a short English sentence for developers. Show your users your own words, and decide what to do from the status, not from the message.

A successful answer is { "data": { … }, "success": true }.The order of checksThe delivery API checks a request in this order and answers with the first problem it finds:

the API key — 401;

whether the product is on for your workspace — 403;

the form of the address — 400;

the item and its version — 404.

Delivery statuses

Status

When

What to do

200

The version was found.

Download and check the package. See Downloading safely.

400

The id is not a UUID, or the version is not a whole number from 1 to 2147483647.

Fix the request. Copy ids from the Developers page.

401

"Missing or invalid API key": no X-Api-Key header, or the key is unknown or revoked.

Check the header and the key. If the key was revoked, issue a new one. See API keys.

403

"Face lenses are not enabled for this tenant" or "Screen effects are not enabled for this tenant".

That product is off for your workspace. The Developers page shows which products are on. Contact IngevoraMirage support to turn one on.

404

"Lens not found" or "Screen effect not found": an unknown id, another workspace's item, an item never published, or a pinned version that doesn't exist. A mistyped path is a 404 too.

Check the id, and check that the item is published. Keep serving what you have cached.

429

"Monthly delivery limit reached". See below.

Keep serving your cached versions. Calls are answered again from the next month, or after a plan change.

500 and other 5xx

Something went wrong on the IngevoraMirage side. A 500 always says "Internal server error".

Retry later, waiting longer between tries, and keep serving your cached versions.

Delivery calls have no per-minute rate limit. A 429 from a delivery route always means the monthly limit.Keep your app workingPlan for errors from the start:

Cache every package you have checked, by id and version. Then an error never leaves your users without a lens.

Treat a failed request as "nothing new" and keep the version you have.

Don't resolve on every launch or every screen. Resolve on your server, on a schedule you choose, and let your apps ask your server.

The monthly delivery limitIf your workspace's plan has a monthly limit on delivery calls, this is how it works:

Every delivery call made with one of your workspace's keys counts. Calls are counted per key and per UTC day, and the limit applies to the workspace's total for the UTC month.

When the total reaches 80 % of the limit, and again at 100 %, the workspace's Owners get an email.

Calls are still served up to 120 % of the limit, so reaching 100 % stops nothing.

Past 120 %, every delivery call answers 429 "Monthly delivery limit reached", until the next UTC month begins or the workspace changes plan.

Downloading manifests and images is never counted. Lenses and effects already on your users' phones keep working.

The less often your server resolves, the further your limit goes. A pinned version's files never change, so once your server has checked them, it doesn't need to ask about that version again.Limits on packagesLimits on layers, images and package size are checked in the editor when you validate and publish, not by the delivery API. See Rules and keep-out zones.Related pages

Delivery API — the routes and their answers.

API keys — issuing and revoking keys.