Agent registration errors

These are errors from registering an agent through the API, recording its runs by hand, and attaching files. Start from the symptom you see: each section below starts from one of them.

​

Retried create duplicated session

A session or message appears twice after you retried a create.

​

Cause

Session and message creates are not retried automatically and do not deduplicate. A retry after an ambiguous response, such as a timeout, can create a second record. sequence_number orders messages; it does not deduplicate them.

​

Solution

1. Read the session and its transcript back before you retry.
2. Retry only the write that is missing.
3. For safe retries of other writes, see Errors and retries.

---

​

File upload returns 413

Sending the bytes for a file artifact fails with 413.

​

Cause

The body is larger than the max_bytes ceiling on the upload ticket.

​

Solution

1. Read max_bytes from the ticket before you send.
2. Request a new ticket with the file’s actual size_bytes.
3. If the file is still larger than max_bytes, split or compress it, then upload again.

---

​

Traces appear under person instead of agent

Runs show up under a person’s identity rather than the registered agent.

​

Cause

The runs were sent with a personal API key. A trace belongs to the identity whose key sent it, never to an agent named in the payload.

​

Solution

1. Copy the agent’s own API key from its Identity tab, where it is shown once when created or rotated.
2. Set it as ATLAN_API_KEY for the agent’s runtime, from an approved secret store.
3. Send a new run and confirm it appears under the agent. See Traces appear under person instead of agent.

---

​

See also

• Register agents through API: The recipe these errors come from.
• Send and verify traces: Confirm runs arrive and are attributed.

​

Need help

If you need assistance after trying these steps, contact Atlan support.