Errors

The one shape of an AdCrunch failure, the field to branch on, the order of the checks, and the codes that more than one operation sends.

The shape of a failure

Each AdCrunch failure has the same JSON body, in each of the four APIs:

{
  "error": "not_found",
  "message": "Skill not found"
}

• error is a stable code. Branch on it. A code does not change for a given failure.
• message is for a person. Show it, or log it. AdCrunch rewrites a message when it can say it better, so never branch on it.

Some failures add a field that tells you what to do next:

The page of each operation lists each status and each code that it sends. The overview lists each operation.

A request that does not match

A request that does not match the schema of its operation answers 400 with error: "invalid_request". The field is missing, it has the wrong type, or the body is not valid JSON. issues names each field. This is POST /assets/uploads with no filename:

{
  "error": "invalid_request",
  "message": "The request does not match the schema. Read issues for each field.",
  "issues": [
    {
      "in": "body",
      "path": "/filename",
      "message": "Invalid input: expected string, received undefined"
    }
  ]
}

• in is the part of the request that holds the field: body, query, params, headers or cookie.
• path is a JSON Pointer into that part. An empty string is the whole part, for example a body that is not valid JSON.
• message is for a person, as above.

The answer never repeats what you sent. The schema of each operation is on its page.

400 and 422

• 400: the request does not have the right shape. invalid_request is the code. Correct the request.
• 422: the request has the right shape, and AdCrunch refuses what it says. The code says why, for example invalid_amount or advertiser_not_owned.

The order of the checks

Each operation checks the API key first, then the permission, then the request. So a request with no key and a bad body answers 401, and a key without the permission answers 403, before the body is read against the schema.

There is one exception. A body that is not valid JSON answers 400 before the API key is checked, because the body is read before any check runs.

A path that does not exist

A path that no operation answers gets 404 with error: "not_found", the same code as a thing that does not exist. The message tells the two apart.

Changed on 2026-09-24. Before this date, a request that did not match the schema answered 422 with the shape of the framework, and a path that did not exist answered the plain text NOT_FOUND. Neither had an error field. In Observe, Context, and Assets, the schema was checked before the API key.

The data of another organization

The API never tells you whether a thing exists in another organization.

• Mutations, Context, and Assets answer 404 with error: "not_found". A thing that never existed gets the same answer. So these APIs never answer 403 for it.
• Observe answers 200. A list is empty, and a read of one entity has an empty body. In Observe, an advertiser of another organization is not a failure.

Codes that more than one operation sends

Live reads

Every Observe operation whose path names an advertiser, such as GET /observe/{advertiserId}/campaigns, is a live read: AdCrunch asks the provider itself, and not what AdCrunch holds. A live read can fail in three ways, and each needs a different action:

What each provider supports lists which resource each provider can read live.