API error codes
Branch on error.code; show error.message to people. See the error shape.
access_denied- You cannot connect clients to that organization.
account_closing- The account is closing and is read-only. Download your export, or ask an owner to cancel the closure.
already_approved- This spec revision was already approved. Read the current revision instead of approving it again.
already_connected- That store is already connected to this workspace.
already_member- You already belong to the workspace this invitation is for. Sign in and open the workspace instead.
already_on_plan- This is already your plan.
already_released- This hold has already been released.
approval_not_pending- This request has already been decided.
approval_right_required- Only members with the spec-approval right can approve.
approver_cannot_use- You approved these figures, so someone else has to seal or use them.
auth_failed- The server refused the credentials.
azure_request_failed- Azure Blob Storage refused the request.
bad_response- An outside service answered with something Instica could not read. Try again later; if it keeps happening, quote the request id.
blocked- The report cannot be prepared until the problems named in error.message are fixed. Fix them and try again.
bundle_component_overlap- That product is already in this bundle for some of the same dates. Change the dates or edit the existing row.
bundle_cross_organization- The component must belong to the same organization.
bundle_cycle- The product you are adding already contains this bundle, so the bundle would contain itself. Choose a different product.
bundle_self_reference- A bundle cannot contain itself.
certificate_expired- The identity provider's signing certificate has expired. Download its current certificate and paste that instead.
client_required- Choose the client this export is for, or All clients.
closure_exists- This account is already closing.
component_not_reusable- Units supplied can only be recorded for a reusable component. Mark the component reusable first.
component_weight_missing- A component in this spec has no weight. Enter a weight for every component, then approve.
confirmation_mismatch- Type the organization name exactly to confirm.
conflictHTTP 409- This conflicts with the current state. Reload and try again.
credentials_invalid- The storage credentials are incomplete or not in the expected form. Enter them again as the provider issues them.
credentials_missing- Add a password or use the generated key.
credentials_unreadable- The stored credentials could not be read. Enter them again.
csrf_failed- The change did not come from an Instica page, so it was refused. Reload the page and try again.
delete_failed- The file could not be deleted.
deletion_already_scheduled- The account is already scheduled for deletion. Cancel that request first if you want to change it.
derived_from_layers- The weight comes from the layers; edit the layers instead.
destination_exists- A file with that name already exists and was not replaced.
destination_not_allowed- That address is not allowed for file flows.
domain_unverified- The email domain is not verified for this organization. Verify the domain in Settings, or sign in with an address on a verified domain.
downgrade_blocked- Reduce seats or entities before moving to this plan.
duplicate_code- Another spec already uses this code.
duplicate_name- A family with this name already exists.
email_failed- The confirmation email could not be sent; Instica retries automatically. Nothing needs to be done.
email_missing- The identity provider did not return an email address.
email_not_verified- The person this request acts for has not verified their email address. Verify it from the email Instica sent, then retry.
email_unverified- The identity provider has not verified this email address.
empty- The file is empty.
empty_file- The file is empty.
empty_rows- Send a non-empty list of rows.
ends_in_past- The evaluation end date must be in the future.
entity_not_found- That legal entity does not exist.
event_missing- The original email is no longer available.
expired- This invitation is past its expiry date. Ask a workspace owner or admin to send a new one.
factor_not_allowed- Your workspace does not allow this factor.
figures_changed- The figures changed after this approval was requested. Ask for approval again.
file_too_large- The file is larger than the upload limit given in error.message. Split it or compress it, then upload again.
file_too_large_for_mcp- The file is too large to send through an AI assistant. Upload it in the web app or through the REST API.
finding_blocking- A blocking finding has to be fixed before the period can lock.
finding_not_found- That finding is not in the latest checks. Run the checks again.
forbiddenHTTP 403- You do not have access to this.
gcs_request_failed- Google Cloud Storage refused the request.
host_key_mismatch- The server's host key is not the one you confirmed.
host_key_not_pinned- Confirm the server's host key before running this flow.
human_action_required- This action needs a signed-in person and is not available to API keys or MCP clients. Open the link to do it in the web app.
idempotency_conflict- Could not reserve the Idempotency-Key. Retry.
idempotency_in_progress- A request with this Idempotency-Key is still running. Retry after it finishes.
idempotency_key_reused- This Idempotency-Key was already used with a different request body. Send a new key for a new request.
idp_unreachable- We could not reach that URL. Check the address and try again.
idp_url_refused- That URL is not allowed. Use your identity provider's public https address.
in_use- Something still uses this record, as error.message names. Remove or move that first, then try again.
inactive- This account is not active.
inputs_invalid- Header values must be text, keyed by field name.
inputs_only_for_amendment- Header values go with an amendment. Save them on the report before asking for approval.
insufficient_scope- The API key is valid but lacks the scope this operation needs. Create a key with that access in Settings, API keys.
internal_error- The operation failed unexpectedly.
interval_not_offered- This plan is not sold with the billing interval you chose. Choose the interval error.message names.
invalid- A value in the request is not valid. error.fields names each field and what it needs.
invalid_account- An account name or code is empty, too long, or unsafe to write into a spreadsheet cell. Send a plain account name or code.
invalid_api_key- The API key is wrong, has expired, or was revoked. Create a new key in Settings, API keys.
invalid_bundle_dates- The bundle dates are not valid dates, or the end is before the start. Send dates like 2026-06-01 with the end on or after the start.
invalid_bundle_quantity- The quantity must be at least 1.
invalid_certificate- This is not a valid X.509 certificate. Paste the whole PEM text from your identity provider, including the BEGIN CERTIFICATE and END CERTIFICATE lines.
invalid_client- The OAuth client is unknown or its authentication failed. Check the client id and secret, or register the client again.
invalid_client_metadata- The body must be a JSON object.
invalid_code- That code is not valid.
invalid_component- Choose one of your active components.
invalid_credential- The passkey could not be verified.
invalid_date_style- The date style is not one the journal export offers. Send dmy, mdy or iso.
invalid_dates- The end date must not be before the start date.
invalid_family- That family does not exist.
invalid_filename- Give a plain file name.
invalid_grant- The authorization code is invalid.
invalid_idempotency_key- Idempotency-Key is too long.
invalid_interval- Choose monthly or annual billing.
invalid_ip_allowlist- An entry in the IP allowlist is not a valid address or range. Use forms like 203.0.113.7 or 203.0.113.0/24.
invalid_jurisdiction- The place code is not an ISO 3166 code. Send a code such as GB or US-CA.
invalid_kind- That export kind is not supported.
invalid_layers- The layers sent for this component are not valid; error.message says which one. Fix that layer and save again.
invalid_link- This spec would apply to the product on the same days as another spec at the same level. Change the dates so they do not overlap.
invalid_options- An option in the request is not one this export offers. Choose from the values the endpoint lists.
invalid_order- List every photo of this spec exactly once.
invalid_path- The folder path is not usable for this connection. Use a relative path without .. segments.
invalid_payload- The webhook body is not an object.
invalid_period- The period must end on or after the day it starts.
invalid_redirect_uri- Redirect URIs must be absolute, without fragment or credentials.
invalid_requestHTTP 400- The request could not be read. Check the body and headers.
invalid_retention- Choose a retention period from 0 to 10 years.
invalid_return_url- The return URL must point back to this application.
invalid_rows- Every row must be a JSON object.
invalid_scope- Choose at least one scope.
invalid_session- That checkout session is not valid.
invalid_signature- The webhook signature is not valid.
invalid_sku- Choose one of your SKUs.
invalid_spec- Choose one of your active specs.
invalid_state- The record is not in a state that allows this action. Reload it and check its status first.
invalid_store- The store address or id is not valid for this provider. Copy it again from the store's admin.
invalid_supply- Component, jurisdiction, period and units are required.
invalid_target- The resource is not served by this authorization server.
invalid_token- The access token is wrong, has expired, or was revoked. Get a new token and retry.
invalid_units- Units supplied must be at least 1.
invalid_variant_of- Choose another spec of your own as the base.
ip_allowlist_needs_break_glass_owner- Turning the IP allowlist on needs an owner who can sign in from anywhere. Choose a break-glass owner first.
ip_allowlist_needs_other_break_glass_owner- This member is the only break-glass owner while the IP allowlist is on. Name another break-glass owner, or turn the allowlist off, first.
ip_allowlist_would_lock_you_out- Your current address is not on the allowlist you are saving, so you would be locked out. Add it first.
ip_not_allowed- Your organization only accepts requests from listed addresses, and this one is not listed. Ask an owner to add it.
job_not_finished- The job has not finished yet.
journal_error- The journal could not be produced; error.message says why. Fix that value and export again.
last_factor- Add another factor before removing this one.
layout_pending- The official file layout for this place is not published yet. Use the PDF or HTML report until it is.
legal_hold- A legal hold keeps this data, so it cannot be deleted now. Ask an owner when the hold will be released.
limit_reached- The spec already has the most photos it can hold. Delete a photo before adding another.
list_failed- The bucket could not be listed.
locked- Too many failed attempts, so this is locked for a while. Wait, then try again.
machine_credential_not_allowed- This operation needs a signed-in person; API keys cannot call it.
measured_requires_measurement- A measured weight needs a recorded measurement. Add the measurement, or choose another data source.
member_removed- This person was removed from the organization, so single sign-on will not add them back. Ask an owner to invite them again.
method_not_allowedHTTP 405- This address does not accept that method.
mfa_enrollment_required- Enrol a second factor to continue.
missing_columns- The file lacks columns the import needs. Map the missing columns, or add them to the file and upload again.
missing_keys- Enter every key from your store.
mixed_currency- The rows use more than one currency, and one journal entry takes one. Export each currency separately.
move_failed- The file could not be moved.
no_billing_contact- The organization has no member to bill.
no_changes- The figures are identical to the sealed version; nothing to amend.
no_components- Add at least one component before approving the spec.
no_diff- This is the first sealed version; there is nothing to compare.
no_fee_schedule- Choose a fee schedule this app has a file for.
no_known_columns- No column in this file matches the format you chose. Check that the first row holds the column names and that you picked the right format.
no_other_approver- No one else can approve this yet. Give a second person the right to sign reports in Team, then ask again.
no_provider- Attach an enabled identity provider before enforcing SSO.
no_workspace- The signed-in account has no EPR workspace yet. Finish setup first.
not_awaiting_mapping- This job is not waiting for a column mapping.
not_cancellable- The grace period has ended; the deletion can no longer be cancelled.
not_confirmable- This invoice was already confirmed.
not_foundHTTP 404- There is nothing at this address. Check the path against the API reference.
not_provisioned- Ask an administrator to invite you before signing in.
not_sftp- Only SFTP connections have a host key.
not_staff- Only Instica staff can grant plan access.
not_syncable- Reconnect this source before syncing.
note_required- Say why this finding is accepted.
note_too_long- The note is longer than allowed; error.message gives the limit. Shorten it and save again.
nothing_to_export- No prepared report is available to send yet.
other_product_data- Another Instica product still holds this organization's data, so it cannot be closed here. Close it in that product first.
overlapping_profile- This spec is already used for the same place by another product on some of the same days. Change the dates so they do not overlap.
overlapping_supply- Units supplied are already recorded for this place over part of the same period. Edit that record instead.
owner_required- Only an owner can cancel the closure.
password_breached- This password appears in a list of breached passwords. Choose a different one.
payload_too_largeHTTP 413- The request body is too large.
payment_declined- Your card was declined, so your plan did not change and nothing was charged. Update your card in Manage billing, then try again.
payment_requiredHTTP 402- Your plan does not include this. Choose a plan in Billing to continue.
period_exists- That reporting period already exists for this entity.
period_locked- This period is already locked.
period_not_locked- Only a locked or submitted period can be amended.
plan_limit_exceeded- This would go past a limit of the current plan. Choose a larger plan in Billing, or remove something first.
plan_not_purchasable- Choose Starter, Growth or Scale. To go back to Free, cancel in the billing portal.
plan_required- The Free plan includes a watermarked preview of CSV, XML and XLSX report files, and this file type cannot carry the watermark. Upgrade to a paid plan to download it.
policy_locks_out_owners- No owner could still sign in under this security policy. An owner must add the required factor, such as a passkey, to their own account first.
policy_locks_out_self- You could not sign in under this security policy with the factors on your account. Add the required factor to your own account first.
preset_kind_mismatch- The import preset is for a different kind of file. Choose a preset made for this kind of import.
preview_expired- The price shown is out of date. Review the change again before confirming.
prices_not_configured- This plan is not available for purchase yet.
private_spec- This is the SKU's own spec; edit its components instead.
purge_blocked- Deleting this data would also delete data other Instica products still use. Remove it from those products first.
rate_limitedHTTP 429- Too many requests. Wait a moment and try again.
read_failed- A file could not be read.
reason_required- Give a reason for the hold.
reason_too_long- The reason is longer than allowed; error.message gives the limit. Shorten it and save again.
record_locked- This period is locked; start an amendment to change it.
report_not_found- No sealed report or prepared file has this hash.
required- A required value is missing. error.fields names each one; send it and try again.
revoked- This invitation was cancelled by the workspace. Ask a workspace owner or admin to send a new one.
sandbox- This is a sandbox; it follows its live organization's plan. Grant access to the live organization.
sandbox_not_billed- Sandbox organizations hold test data only and are never billed.
sandbox_organization- A sandbox closes with its live organization. Close the live account instead.
seat_limit_reached- The plan has no free seat for this person. Free a seat or choose a larger plan, then sign in again.
second_approval_outdated- The figures changed after they were approved. Ask for approval again.
second_approval_required- Your organization requires a second person to approve these figures first.
self_approval_refused- You asked for this approval, so someone else has to give it.
server_errorHTTP 500- Something went wrong on our side. Try again; if it keeps happening, quote the request id.
session_expired- The session ended. Sign in again, then retry.
signature_blank- Draw or type your signature before signing.
signature_font_invalid- Choose one of the offered signature styles.
signature_image_invalid- The signature must be a PNG image.
signature_method_invalid- Choose to draw or type your signature.
signature_name_mismatch- A typed signature must match the signer's name.
signature_too_large- The signature image is too large.
signer_name_required- Enter the signer's full name before signing.
sole_owner- You are the only owner of a workspace. Add another owner or close the workspace first.
spec_retired- A retired spec cannot be approved.
ssh_handshake_failed- The SSH handshake with the server failed.
sso_disabled- This single sign-on connection is turned off. Sign in with your password.
sso_failed- Single sign-on could not finish; error.message says why. Check the identity provider settings and try again.
sso_not_in_plan- Single sign-on is not part of this organization's plan. Sign in with your password or ask an owner to upgrade.
sso_state_invalid- This sign-in link has expired or was already used. Start again.
stale- The data file changed since this proposal was written; propose the change again.
statement_changed- The sign-off statement has changed since you opened this page. Reload to read it, then sign.
step_up_required- This action needs a fresh check of your second factor. Confirm it is you with an authenticator code or a passkey, then repeat the action.
stripe_managed- This organization pays through Stripe, so its plan changes there, not here.
sync_in_progress- A sync is already running for this connection.
template_already_applied- This packaging template was already applied to the product. Edit the parts it added instead.
terms_reacceptance_required- The terms changed since they were accepted. Review and accept the new terms in the web app, then retry.
token_expired- This link has expired.
token_invalid- This link is not valid.
too_large- The photo is larger than 10 MB.
too_long- The text is longer than allowed; error.message gives the limit. Shorten it and save again.
too_many_rows- The bulk job has more rows than one job takes; error.message gives the limit. Split the rows across several jobs.
trust_document_not_found- There is no trust document by that name.
two_person_rule- A different staff user must review this proposal.
unauthenticatedHTTP 401- Sign in, or send a valid API key in the Authorization header.
unknown_client- That client is not in this workspace or not in your access.
unknown_jurisdiction- No report format is defined for that place. Choose a place Instica reports for.
unknown_material- Choose a material from the taxonomy.
unknown_plan- There is no plan with that name. Use a plan id from the plan catalog.
unknown_preset- There is no import preset with that id. List the presets and choose one of them.
unknown_provider- That provider is not supported.
unknown_tool- That accounting tool is not supported. Send xero, qbo or netsuite.
unreadable- The image could not be read.
unreadable_file- The file is not a valid XLSX workbook.
unresolved_flags- Data-quality flags are still open on these records. Resolve the flags listed in flag_ids, then try again.
unsupported_api_version- The Epr-Version header names a version this API does not publish. error.fields.supported lists the versions you can send.
unsupported_file- That file type cannot be uploaded here. Upload a PDF, an image, a CSV or an XLSX file.
unsupported_format- Use kind=json, html or pdf.
unsupported_grant_type- Supported grants: client_credentials, authorization_code, refresh_token.
unsupported_media_typeHTTP 415- Send the body as JSON, or as multipart for file uploads.
unsupported_response_type- Only response_type code is supported.
unsupported_transport- That transport is not supported.
unsupported_type- Upload a PNG, JPEG or WebP image.
upload_token_invalid- This upload link is invalid or has expired.
used- This invitation has already been accepted. Sign in with the account that accepted it.
validation_error- A value in the request is not valid. error.message or error.fields says which one and what it needs.
validation_failedHTTP 422- Some fields need attention.
version_not_found- No sealed version exists for that format.
version_superseded- A newer version of this report has been sealed; sign the latest version instead.
workspace_read_only- The workspace is read-only, so changes are refused. Billing and data export still work; choose a plan in Billing to make changes again.
workspace_setup_required- Finish setting up your workspace to see plans and billing.
write_failed- The file could not be written.
wrong_account- This invitation was sent to a different email address. Sign in with that address, or ask for an invitation to yours.