Account error codes
Every public API error code emitted by Account, with its HTTP status, its type and a page per code.
Error codes emitted by Account. Each code links to its own page with the cause and the action to take.
| Code | Type | HTTP | Description |
|---|---|---|---|
access_level_raise_forbidden | invalid_request_error | 422 | Someone tried to raise the access level on a managed account whose holder has already claimed it. Since the claim only the holder can raise that level; the provider can only lower it. |
account_not_found | not_found_error | 404 | The account behind the key could not be resolved, which usually means the key no longer points at a live company. |
administrator_key_not_grantable | invalid_request_error | 422 | One of the sections in grants is an Administrator key (user management, plan and subscription, API and developers or digital certificate) and those sections are never granted to a member. |
api_key_already_revoked | invalid_request_error | 422 | The key was already revoked, and a revoked key admits no further operations: revocation is terminal. |
api_key_not_found | not_found_error | 404 | The identifier does not match any API key of the authenticated company. |
enterprise_contract_transition_required | invalid_request_error | 422 | The managed account has an enterprise contract and, on ending the management, its payment would move to the holder before Factuarea has set the plan it continues on. A subscription is never created without a price, so nothing was changed. |
external_advisor_already_assigned | invalid_request_error | 422 | The account already has an external advisor marked: there can only be one per account. |
grant_company_not_in_account | invalid_request_error | 422 | The grant's tax ID is not a real tax ID of the account, or it is outside the credential's tax ID scope. Both cases get the same answer, without telling which. |
grants_only_for_member | invalid_request_error | 422 | Only a member with the member role can hold per tax ID permissions (grants). The owner (owner) and the administrators (admin) reach every tax ID of the account, so a grant on them would mean nothing. |
import_file_invalid | invalid_request_error | 422 | One of the import files cannot be read with the template format: it is not a readable CSV, its header does not appear within its first 20 lines, it lacks a required column or it has a broken line. param says which file fails (accounts_file or customers_file) and the message names the column or the line. Nothing was written. |
import_file_too_large | invalid_request_error | 413 | One of the import files exceeds 5 MB. The size is checked before reading any row, so nothing was processed or written. param says which file fails (accounts_file or customers_file). |
import_in_progress | conflict_error | 409 | A bulk import of this provider account is already in progress. Imports of the same account are applied one at a time so that no account, charge or tax ID is created twice, so this one was not applied and nothing was written. |
import_row_limit_exceeded | invalid_request_error | 422 | One of the import files carries more rows than a single import accepts: 100 in the accounts file (accounts_file) and 1,000 in the customers file (customers_file). Rows are counted before being read, so nothing was processed or written. param says which file fails. |
invitation_expired | invalid_request_error | 422 | The invitation exists and belongs to this company, but its acceptance window already closed, so the person who received it can no longer redeem it. |
invitation_not_found | not_found_error | 404 | The identifier matches no pending invitation of the authenticated company: it may have been cancelled, already accepted, or issued by a different company. |
live_credential_required | authorization_error | 403 | A test key tried to change a live account. It only happens on the operations that change the account —members, invitations, ownership, tax ID transfers, NIF portfolio, keys and seats—: a test key cannot alter real data. |
managed_account_external_ref_in_other_environment | conflict_error | 409 | The external reference is already used by a managed account of the other environment (live or test). The reference is unique across both environments, and the answer does not name that account because this environment does not list it. Nothing was written. |
managed_account_not_claimable | invalid_request_error | 422 | The managed account is a test one, and a test account is never claimed: it has no claim voucher to issue or reissue. |
managed_account_plan_not_self_serve | invalid_request_error | 422 | The enterprise plan was requested for a managed account. A managed account is created or changed on emprendedor or empresario; enterprise is only assigned by Factuarea under contract. |
managed_account_provider_in_trial | invalid_request_error | 422 | The provider account is on its trial period and requested a live managed account, which is charged. During the trial only test managed accounts can be created. |
managed_accounts_limit_reached | invalid_request_error | 422 | The provider account already has as many live managed accounts under active management as its cap allows. Test managed accounts do not count towards that cap. |
member_is_last_owner | invalid_request_error | 422 | The operation would leave the NIF with nobody able to administer it: the member being removed, or demoted to a role without administration, is the last one holding the owner or admin role in that NIF. |
member_not_found | not_found_error | 404 | The identifier matches nobody on the account team: either that person was never a member of the authenticated company, or they belong to a different one. The account surface answers both cases alike. |
module_not_grantable | invalid_request_error | 422 | One of the sections in grants cannot be granted: it is not an administrator-only section (a member already reaches it with normal permissions) or the company does not have it in its plan. |
nif_transfer_expired | invalid_request_error | 422 | The tax ID transfer was genuinely issued, but its validity period ran out. Unlike an unrecognised transfer, this answer only reaches whoever already held a real one, so it reveals nothing new. |
nif_transfer_invalid | invalid_request_error | 422 | The tax ID transfer presented authorizes nothing: its secret is mistyped, truncated, already consumed, or was never issued. All of those answer alike on purpose, so the operation cannot be used to probe which transfers exist. |
owner_transfer_forbidden | authorization_error | 403 | The caller is not allowed to transfer ownership of the account: either they are not the current owner, or the proposed recipient cannot hold it. This is a matter of permission, not of a malformed payload. |
permissions_not_applicable_to_administrator | invalid_request_error | 422 | The member is an owner or admin of the account: they hold every permission of their plan and take neither restrictions nor section grants. |
permissions_not_applicable_to_employee | invalid_request_error | 422 | The person is an employee of the employee portal: their access is governed by the portal, not by the section matrix, so they take neither restrictions nor grants. |
plan_limit_exceeded | payment_required_error | 402 | The company has reached a resource limit for its plan. |
privileged_scope_required | authorization_error | 403 | The operation requires the account provider privilege (accounts:read or accounts:write) and it is not met: either the key's account has not been granted it, or the person who issued the key is no longer an owner or administrator of the account. Both causes answer alike. |
provisioning_account_claimed | conflict_error | 409 | The holder has already claimed this managed account and runs it on their own: it can no longer be claimed again, have its claim voucher reissued or be provisioned again with the same external reference. |
relation_already_exists | invalid_request_error | 422 | There is already a pending or active access between these two accounts, and only one can be open for each pair of accounts. |
relation_company_not_in_grantor | invalid_request_error | 422 | The list of tax IDs of the access is not valid: either it names a tax ID that does not belong to the account granting the access, or it is empty. The error points at the company_ids field and does not tell which tax ID fails. |
relation_invitation_expired | invalid_request_error | 422 | The access invitation exists and is still pending, but its acceptance window ran out, so it can no longer be accepted. |
relation_invitation_invalid | invalid_request_error | 422 | The access invitation presented is no good: its secret does not exist, was already used, was revoked or is addressed to another account. All of those answer alike on purpose, so the operation cannot be used to probe other accounts' invitations. |
relation_self_grant_not_allowed | invalid_request_error | 422 | The account given cannot receive the access: either it is the same account granting it, or the identifier does not match a valid account. Both cases answer alike. |
relation_transition_not_allowed | invalid_request_error | 422 | The access between accounts is in a state that does not admit the requested change: for example, accepting one that is already active or resending the invitation of one that has ended. |
sender_identity_not_verified | invalid_request_error | 422 | The sending company has not proven its identity yet, and without that it cannot write to external recipients from the shared sender domain. This is neither an exhausted quota nor a permission problem: the credential holds the scope, and waiting does not clear it. |
Related
Error codes by category
Find an error by the category that emits it.
Full reference table
All codes, HTTP statuses, types and descriptions in one reference.
Error model
Interpret the error envelope and handle errors by code.