Handle rejected signups

Qualia declines signups it cannot research usefully, such as throwaway addresses, so you do not spend credits on them. This guide explains each rejection reason and shows you how to fix a signup that was missing context.

A rejected signup still gets a normal create response: 201 Created with "status": "created". Read the actor to see the result. Its status is rejected, and rejectionReason says why:

{
  "id": "h8tq1xw4mcz7p2kd9ve0rjsl",
  "email": "alex.reyes@gmail.com",
  "name": null,
  "status": "rejected",
  "rejectionReason": "insufficient_context",
  "failureReason": null,
  "score": null,
  "scoringStatus": "pending",
  "title": null,
  "linkedinUrl": null,
  "location": null,
  "companyName": null,
  "companyDomain": null,
  "industry": null,
  "companyLocation": null,
  "createdAt": "2026-09-29T15:20:03.114Z",
  "enrichedAt": null,
  "summary": null,
  "highlights": null,
  "bio": null,
  "companyDescription": null
}

Rejected signups use no credits.

Rejection reasons

`rejectionReason`	What it means	What to do
`insufficient_context`	The email is from a personal provider, such as Gmail, and the request had no `name` and no company, title, or LinkedIn details. Qualia has nothing to research.	Send the same email again with a `name` or company details. See Fix insufficient context.
`disposable_email`	The address uses a disposable or throwaway email service, or a domain with no active website. It is unlikely to reach a real person.	Nothing. You can also block these addresses in your sign-up form. See Send a rejected email again.
`suspicious_email`	The address or the signup pattern looks automated.	Nothing. See Send a rejected email again.
`invalid_email`	The address is not a valid email address.	Ask the user to correct it. A corrected address creates a new actor.
`quota_exceeded`	Your credits ran out after Qualia accepted the signup and before research started.	Add credits in Settings → Billing so new signups get researched. This signup stays rejected: resending the email does not research it, even after you add credits.

Fix insufficient context

Send the same email to POST /v1/actors again, this time with a name or at least one company, title, LinkedIn, or work email key in metadata. Qualia saves the new name and metadata, moves the actor back to pending, and researches it. The response is 200 OK with "status": "already_exists" and the same actorId.

The resend needs credits. When your balance is empty, it returns 402 and the actor stays rejected.

const { data: actor } = await qualia.getActor({ path: { actorId } });

if (
  actor?.status === "rejected" &&
  actor.rejectionReason === "insufficient_context"
) {
  // Use what you know about the user, for example from their profile form.
  await qualia.createActor({
    body: {
      email: actor.email,
      name: "Alex Reyes",
      metadata: { company: "Acme Robotics", title: "Head of Operations" },
    },
  });
}

Then poll the actor again until it reaches a final status.

To avoid this rejection, send a name or company details in the first request. A common pattern is to send the signup after the user completes a profile step in onboarding. Actors lists every metadata key Qualia recognizes.

Send a rejected email again

When you send an email that Qualia already rejected, it runs its signup checks again on the new request. If the request passes, Qualia saves any new name and metadata, moves the actor back to pending, and researches it. If it does not pass, nothing changes. Either way, the response is 200 OK with "status": "already_exists", so read the actor to see what happened.

`rejectionReason`	What resending the same email does
`insufficient_context`	Research starts if the new request includes a `name` or a recognized `metadata` key.
`disposable_email`, `suspicious_email`	Qualia checks the address again. Checks on the address itself give the same result. Some other checks can give a different result later, and then research starts.
`invalid_email`	The address is rejected again.
`quota_exceeded`	Nothing. Qualia does not research the signup again, even after you add credits.

A resend never changes a failed actor. See When a run fails.

Rejected and failed are different

rejected means Qualia chose not to research the signup. failed means research started and hit an error. Neither uses credits. For failed runs, see When a run fails.

Next steps

Send signups to Qualia. Send the context that prevents rejections.
Actors. Every status and how actors move between them.

Spot a rejected signup

Rejection reasons

Fix insufficient context

Send a rejected email again

Rejected and failed are different

Next steps

On this page