Errors

The status codes and error bodies the partner API returns.

The error body¶

An error response from the partner API is a JSON object with a single detail key. Its value takes one of three shapes.

A string, for most errors:

{"detail": "Engagement not found"}

A list, when the request fails validation (422). Each entry names the failing location in loc, a machine-readable type and a message in msg:

{
  "detail": [
    {
      "type": "missing",
      "loc": ["body", "events"],
      "msg": "Field required",
      "input": {"url": "x"}
    }
  ]
}

An object, in three cases: 409 on engagement submit ({message, blocked[]}), and 422 or 503 on asset verify ({outcome, reason}).

The one exception is an unhandled server error. It is answered 500 with Content-Type: text/plain and the body Internal Server Error, not JSON.

Status codes¶

Status	When the partner API returns it	`detail`	Described in
`400`	Submit of an engagement that is not `pending` or `blocked`	string	Engagements
`401`	No key, a key that matches no active key, or a key whose organization is gone	string	Authentication
`404`	An id that does not exist or belongs to another organization; an engagement with no report; a path that matches no route	string	Engagements, Reports
`405`	A method the path does not support, for example `DELETE` on an engagement	string, `Method Not Allowed`	Partner API
`409`	Registering a duplicate asset, or deleting an asset with verification history	string	Assets
`409`	Submit refused by the launch gate	object	Engagements
`422`	Request validation: a missing or mistyped field, a malformed id in the path, a body that is not valid JSON, an invalid cadence	list	Assets, Engagements, Schedules, Webhooks
`422`	An asset value invalid for its kind, an unknown parent asset, or verify on an asset with no automated method	string	Assets
`422`	Verify ended in `fail`	object	Assets
`500`	An organization with no user, on an endpoint that acts as a user	string, `No user found for organization`	Authentication
`500`	An unhandled error: a `framework` value over 50 characters on an engagement or a schedule, a webhook `url` over 500 characters, an asset `value` over 255 characters, a schedule PATCH whose expression and timezone fail together, or a submit whose job cannot be queued	none: plain text	Assets, Engagements, Schedules, Webhooks
`503`	Verify ended in `error`	object	Assets

A successful DELETE answers 204 with no body. A path sent with a trailing slash, such as /api/v1/engagements/, is answered 307 with a redirect; send paths exactly as the endpoint table lists them.

Timestamps¶

Timestamps in responses are ISO 8601 strings in UTC. Whether a timestamp carries an offset suffix depends on the endpoint and the database, so parse them as UTC whether or not the suffix is present. Schedule timestamps and preview run times always end in +00:00.

Last updated 2026-09-24