Errors

Every v1 error is a problem document (RFC 7807, application/problem+json). Its type is this page with the error's code as the anchor, for example https://docs.aleta.ai/developers/api/v1/errors#in_use.

The problem document

JSON

{
  "type": "https://docs.aleta.ai/developers/api/v1/errors#in_use",
  "title": "Conflict",
  "status": 409,
  "code": "in_use",
  "detail": "Cash account 6b1d2f0a-3c4e-4f5a-8b7c-9d0e1f2a3b4c is used by transactions.",
  "next_action": {
    "next": "end_date",
    "method": "PATCH",
    "path": "/v1/cash-accounts/6b1d2f0a-3c4e-4f5a-8b7c-9d0e1f2a3b4c",
    "field": "valid_to"
  }
}

Match on code, never on detail: detail is for people and its wording can change. title is the HTTP reason phrase of status. Some codes add fields: next_action names the call to make instead (in_use, already_exists, aleta_owned, period_locked and most 409 codes; null when there is no other step), and period_locked adds locked, the accounts that are locked. A 429 and a 503 carry Retry-After. v2 and v3 keep their own error format.

Codes

code	status	when
`bad_request`	400	The request is malformed: a field is missing, has the wrong type or is out of range. `detail` names the field. Most lists also refuse a query parameter they do not know. A read of one row, a route that takes no query parameters (for example `GET /v1/currencies`, `GET /v1/roles`, `GET /v1/users/me`), and the lists `GET /v1/invites`, `GET /v1/access-grants`, `GET /v1/price-hierarchies`, `GET /v1/exchange-rate-hierarchies` and `GET /v1/basic-data-hierarchies` ignore unknown query parameters.
`unauthorized`	401	No bearer token, or the token is expired or not valid for v1.
`forbidden`	403	The key may not make this call, or may not read or write this row. When there is a way out, `detail` names it.
`not_licensed`	403	The data licence does not cover the series and you have no points of your own. See the data licence.
`aleta_owned`	403	The row is shared data owned by Aleta (`owner: aleta`), which only Aleta changes. Add your own row instead; `next_action` names the route when there is one.
`not_found`	404	No such path, or no such row for your tenant or for a client you see. A retired route answers the same.
`conflict`	409	The write conflicts with the stored state, for example a unique value another row already has. `detail` says which.
`already_exists`	409	A row with the same natural key exists. `next_action` names the call that changes it, when you may.
`in_use`	409	The resource has had an effect on figures, so it is not deleted. `next_action` names the call to make instead (`archive`, `end_date`, `offboard`, `reverse`, `anonymize`, `pause`, `delete` or `ask_aleta`).
`legacy_managed`	409	The row comes from the legacy platform, which still runs your data. It is read-only in v1 until your move to v1 is done.
`period_locked`	409	The write is dated on or before the closing date of an entity whose account it touches. `locked` lists the accounts; `next_action` points to the period lock.
`rate_limited`	429	Too many calls in a minute, or the key's daily write quota is spent. `Retry-After` gives the seconds to wait.
`internal`	500	An error on Aleta's side. Retry later; if it repeats, tell Aleta the time and the path.
`not_implemented`	501	The route exists but does not take this call.
`bad_gateway`	502	A service v1 forwards to did not answer. Retry later.
`tenant_overloaded`	503	Your tenant has too many calls running at once. Retry after `Retry-After`.
`analytics_unavailable`	503	Your figures are not ready to read yet. Retry after `Retry-After`.
`service_unavailable`	503	The service is briefly unavailable. Retry after `Retry-After`.

Codes of one rule

These codes name the rule a request or the stored state broke. The resource's page says when each is sent.

code	status	when
`confirmation_required`	400	A tenant closure without `confirmed_by`, or with a user who is not active Aleta staff.
`invalid_rule`	400	A lens rule's `ref` is not an id.
`lens_needs_client`	400	A lens at the top without `client_id`.
`lens_needs_parent`	400	`show_as_portfolio` on a lens at the top.
`lens_needs_rules`	400	A lens moves under a parent that does not hold its accounts, without `rules`.
`lens_parent_client`	400	A lens under a lens of another client.
`ownership_cycle`	400	An ownership would make an entity own itself.
`ownership_over_100`	400	An ownership would take the economic shares in an entity past 100 %.
`reason_required`	400	A tenant closure without `reason`.
`too_many_rules`	400	A lens with more rules than it takes.
`admin_in_no_group`	409	An admin added to a group: an admin sees everything and is in no group.
`already_closed`	409	The client, or the import issue, is already closed.
`already_configured`	409	The client already has a risk-rate config.
`already_ended`	409	The risk-rate config has already ended.
`already_live`	409	The client is live; its onboarding status can no longer change.
`already_member`	409	The user is already in the group.
`already_open`	409	The reconciliation break is open; only a resolved or waived break is reopened.
`authority_closed`	409	Files, consent, link or activate on a revoked or cancelled custodian authority.
`checks_failed`	409	A publish run's checks failed; send `force` with a reason to release anyway.
`concurrent_change`	409	Another write changed the custodian authority meanwhile. Retry.
`consent_conflict`	409	An `all` consent while a `specific` authority exists for the same entity and custodian.
`consent_overlap`	409	A `specific` consent of a number another authority already covers.
`consent_required`	409	A link before consent on a custodian authority that is not active.
`duplicate_account`	409	Another open cash or custody account at the custodian has the same number.
`external_reference_taken`	409	Another party has this `external_reference_id`.
`flow_outdated`	409	A custodian authority opened on an outdated auth flow.
`invalid_status`	409	Consent on a custodian authority that is not waiting for files or consent.
`later_version`	409	A later lot method version exists; switch from a date after it.
`lens_cycle`	409	A lens under itself or one of its sub-lenses.
`locked`	409	The client's structure lens, which is locked.
`mixed_cluster`	409	Linked cash and custody accounts released or run in different ways.
`module_not_enabled`	409	The tenant does not have the module.
`name_taken`	409	A group with that name exists.
`no_currency`	409	The write needs the asset's currency and the asset has none. `next_action` names the asset's `PATCH`.
`not_available_yet`	409	The transaction type is not available on your tenant.
`not_consented`	409	A link of a number the `specific` consent does not cover.
`not_datable`	409	A risk-rate config that cannot be dated.
`not_retryable`	409	The import issue cannot be taken in again; discard it.
`nothing_staged`	409	A release of a publish run with nothing staged.
`ownership_overlap`	409	The owner already owns the entity in that period.
`owns_outside_client`	409	A client closes while an entity under it owns an entity outside it.
`read_only`	409	Aleta's standard report definitions are read-only; copy one with `copy_from`.
`release_unavailable`	409	Releasing this kind of publish run by hand is not available.
`reprocessing_unavailable`	409	v1 cannot take this import issue in again; discard it.
`revision_mismatch`	409	The report definition changed since `expected_revision`; read it again.
`revoke_in_progress`	409	Aleta is finishing a revoke of the custodian authority.
`standard_group`	409	A standard group cannot be archived or renamed.
`starts_after_close`	409	A client closes before something under it starts.
`unreadable_config`	409	The client has a risk-rate config v1 cannot read; it is not overwritten.
`currency_required`	422	`primary_currency: null`: an entity always has one.
`dated_versions_unavailable`	422	Dated benchmark components are not available for your tenant.
`effective_from_currency_only`	422	`effective_from` on an entity change that is not a currency change.
`effective_from_in_future`	422	`effective_from` is after the last day v1 can apply.
`effective_from_outside_config`	422	`effective_from` is outside the risk-rate config's period.
`effective_from_outside_versions`	422	`effective_from` is outside the benchmark's versions.
`empty_patch`	422	A `PATCH` with no field to change.
`file_too_large`	422	The report file is too large to download through the API.
`no_holding`	422	The import issue carries no dated holding to store; discard it.
`no_structure_access`	422	The user sees none of the lens's accounts; give access first.
`outside_entity_currency`	422	The entity has no primary currency on that day.
`unknown_holding_target`	422	The holding names a custody account or asset your tenant does not have; discard the issue.
`valid_to_in_future`	422	`valid_to` is after the last day v1 can apply.