Errors
Every error code, what it means, and whether to retry, fix something, or fetch a person.
Failures use standard HTTP status codes and carry a stable code. A status of 400 or above is a failed step — that is how automation platforms treat it.
error
{
"error": {
"code": "agent_offline",
"message": "The connector isn't running on OFFICE-PC. Open it, wait for \"Connected\", then re-run this step.",
"type": "unavailable",
"retryable": true
},
"meta": { "request_id": "req_c19e…" }
}| Field | Means |
|---|---|
code | Stable. Branch a workflow on this. |
message | Written for the person reading it, naming the next step. |
type | The category, which follows the status: invalid_request, authentication, plan_limit, permission, not_found, conflict, validation, rate_limit, unavailable, outcome_unknown, internal. |
retryable | Whether the same request can succeed later with nothing changed. On a 429 or 503, wait Retry-After seconds first. |
field | The input the error is about, when one is known. |
details | Extra facts for some codes — for example the godowns to choose from. |
Retrythe same request lands on the same record
Fix, then retrythe same request fails the same way until something changes
Needs a personsomebody has to attend to that computer
Something is wrong with TallyPrime
These are the ones your users will actually see. Every message names the next action, so showing it unchanged is almost always the right thing to do.
| Code | Status | Means | Then |
|---|---|---|---|
agent_offline | 503 | The connector is not running on that computer. | Needs a person |
tally_not_open | 503 | TallyPrime is not open on that computer. | Needs a person |
tally_starting | 503 | TallyPrime is still opening. Re-running the step shortly succeeds. | Retry |
tally_unreachable | 503 | TallyPrime is not answering. Its connectivity setting is probably off. | Needs a person |
company_not_loaded | 503 | No company is open in TallyPrime. | Needs a person |
company_mismatch | 409 | A different company is open than this connection is bound to. | Needs a person |
tally_busy_dialog | 503 | TallyPrime is waiting on a message box that someone must close. | Needs a person |
tally_not_responding | 503 | TallyPrime has stopped responding and may need restarting. | Needs a person |
agent_busy | 503 | Too many steps are queued for that computer at once. Nothing was sent. | Retry |
tally_timeout | 504 | No answer in time. Re-running the step updates the same record. | Retry |
not_verified | 502 | Tally reported success but the record could not be read back. | Retry |
Something is wrong with the data
| Code | Status | Means | Then |
|---|---|---|---|
ledger_not_found | 422 | A ledger named in the request does not exist. | Fix, then retry |
item_not_found | 422 | A stock item named in the request does not exist. | Fix, then retry |
godown_required | 422 | The company uses several godowns and the line did not say which. The message lists them. | Fix, then retry |
unbalanced_entry | 422 | The totals do not add up. Nothing was written. | Fix, then retry |
bill_wise_off | 422 | Bills were listed to settle but that party has no bill-by-bill tracking. Nothing was written. | Fix, then retry |
ledger_exists | 409 | ledgers.create found a ledger with that name. Use ledgers.find_or_create or ledgers.create_or_update if that is expected. | Fix, then retry |
item_exists | 409 | stock_items.create found a stock item with that name. | Fix, then retry |
ledger_group_mismatch | 409 | A ledger with that name already exists under a different group. Nothing was changed. | Fix, then retry |
ledger_gstin_mismatch | 409 | A ledger with that name already exists with another party's GSTIN. Nothing was changed. | Fix, then retry |
duplicate_invoice | 409 | That invoice or bill number is already recorded for that party. Nothing was added. | Fix, then retry |
group_not_found | 422 | The group named for the ledger does not exist in the company. | Fix, then retry |
duplicate_number | 422 | The number sent is already on another entry of the same type, and TallyPrime is set to prevent duplicates. The message names that entry. | Fix, then retry |
voucher_type_unavailable | 422 | The voucher type does not exist in the company, or is switched off. | Fix, then retry |
tally_rejected | 422 | TallyPrime refused the entry. The message quotes its reason where it gave one, and names the cause where a read can find it. | Fix, then retry |
bad_request | 400 | A required field is missing or a value is malformed. field names it. | Fix, then retry |
validation_failed | 422 | Several fields need fixing. details names each one. | Fix, then retry |
not_found | 404 | No operation, list or record by that name — for example ledgers.get on a name TallyPrime does not have. | Fix, then retry |
method_not_allowed | 405 | A write was sent as GET. Send it as POST with a JSON body. | Fix, then retry |
Access and limits
| Code | Status | Means | Then |
|---|---|---|---|
unauthenticated | 401 | No token, or it is not recognised. | Fix, then retry |
access_revoked | 401 | The authorization was revoked. Reconnect the application. | Needs a person |
token_expired | 401 | The access token has expired. Refresh it with the refresh token and send the request again. | Retry |
invalid_grant | 400 | The code or refresh token is expired, used or does not match. | Fix, then retry |
forbidden | 403 | The token does not carry the permission this operation needs. | Fix, then retry |
connection_revoked | 409 | The TallyPrime connection was disconnected in the dashboard. | Needs a person |
connection_unauthorized | 409 | The TallyPrime connection is no longer authorized. Reconnect it from the dashboard. | Needs a person |
connection_not_ready | 409 | Pairing was never finished for that connection. | Needs a person |
plan_limit_reached | 402 | The monthly operation allowance is used up. | Needs a person |
too_many_requests | 429 | Rate limited. Retry-After says how long to wait. | Retry |
Retrying safely
Retry means exactly that: re-running a write with the same body lands on the same record rather than creating a second one, so a retry loop is safe.
Fix, then retry means the same request will fail the same way. Change the data — or create the missing ledger — first.
Needs a person means the computer running TallyPrime wants attention. Retrying may work once someone has been to it.
Something missing on this page? Tell us and we will fix it.