Error codes

Common error codes and how to resolve them

Falu uses HTTP response status codes to indicate the success or failure of an API request. If a request fails, Falu returns an error using the appropriate status code.

Generally, these status codes can be categorized into three groups:

  • 2xx success status codes confirm that a request worked as expected.
  • 4xx error status codes indicate an error because of the information provided (e.g. a required parameter was omitted, or a referenced object does not exist)
  • 5xx error status codes are rare and indicate an error within Falu's servers.

Some 4xx errors that could be handled programmatically (e.g. insufficient_balance) include a detail - a short string with a brief explanation - as a value for title.

Below is a list of possible error codes that can be returned, along with additional information about how to resolve them. Falu server strictly follows the Problem Details for HTTP APIs standard - RFC7808 for these type of errors.

For convenience, the error's type property is a direct link to the specific error code it corresponds to.

invalid_workspace_state

The workspace is in an invalid state and is not allowed to make a request in live mode. Returned when the workspace has been suspended due to billing issues or if the workspace has been suspended due to misuse or fraud investigations.

features_disabled

The request or operation requires one or more features that are currently disabled or have not been enabled for the workspace.

invalid_settings

The settings required for a given request in the workspace are invalid, malformed, or lack information required to support the request.

idempotency_key_invalid

Idempotency key provided is invalid due to length either exceeding 128 characters or containing invalid characters.

idempotency_error

Idempotency cannot be performed on this request. Typically returned when the request body does not match the one from an earlier request and hence cannot be made idempotent.

idempotency_key_in_use

The idempotency key provided is currently being used in another request. Occurs if an integration is making duplicate requests simultaneously.

insufficient_balance

The account does not have enough funds to perform the request. See the error detail for more information.

object_redacted

The object targeted has already been redacted and cannot be updated.

object_cannot_be_redacted

The object targeted cannot be redacted. Mostly happens when the object's status indicates an operation in progress. To resolve, wait for the operation to complete or fail. See the error detail for more information.

object_redaction_in_progress

Redaction for the object targeted has already begun and cannot be reinitiated.

identity_verification_not_found

The target identity verification could not be found.

identity_verification_cannot_be_modified

The identity verification cannot be updated. Happens when status is not input_required. Try to cancel or redact instead.

identity_verification_cannot_be_cancelled

The identity verification cannot be cancelled. Happens when status is not input_required. To resolve, wait for processing to complete or to fail and return to the input_required state.

customer_not_found

The target customer could not be found.

event_not_found

The target event could not be found.

event_delivery_cannot_be_retried

The event delivery cannot be retried. See the error detail for more information.

file_not_found

The target file could not be found.

file_expired

The file has already expired and has been purged. It cannot be downloaded or be used to create a link.

file_type_not_allowed

The type of content in the file is not allowed. Allowed types are: application/pdf, image/png, image/jpeg, and text/csv.

file_invalid

The file has invalid content. This varies depending on content. See the error detail for more information.

file_cannot_be_downloaded

The purpose for which the file was created does not allow downloading or creates unauthenticated links.

The target file link could not be found.

The target file link cannot be updated. Happens when the file link has already expired. To resolve, create a new file link.

payment_not_found

The target payment could not be found.

payment_cannot_be_refunded

The specified payment cannot be refunded because it has already been refunded, is in the process of being refunded or, is not in a refundable state.

payment_authorization_not_found

The target payment authorization could not be found.

payment_authorization_closed

The payment authorization has already been closed and, thus, cannot be approved or declined. Payment authorizations can only be approved/declined when in pending state.

payment_refund_not_found

The target payment refund could not be found.

transfer_not_found

The target transfer could not be found.

transfer_cannot_be_reversed

The specified transfer cannot be reversed because it has already been reversed, is in the process of being reversed, or is not in a reversible state.

transfer_reversal_not_found

The target transfer reversal could not be found.

message_not_found

The target message could not be found.

message_cannot_be_cancelled

The message cannot be cancelled. Happens when status is not accepted indicating the messages has already been sent or is currently being sent.

message_media_invalid

The media for the message is invalid. Happens when the file provided is of a different purpose or the URL provided contains a file that does not meet the requirements for message media.

message_batch_not_found

The target message batch could not be found.

message_batch_cannot_be_cancelled

The message batch cannot be cancelled. Happens when status is not accepted indicating the messages has already been sent or is currently being sent.

message_sender_not_found

The target message sender could not be found.

message_sender_alphanumeric_in_use

The alphanumeric value is already in use by another message sender in the message stream.

message_sender_cannot_be_modified

The message sender cannot be updated or deleted. See the error detail for more information.

message_stream_not_found

The target message stream could not be found.

message_stream_name_in_use

The name is already in use by another message stream in the workspace.

message_stream_archived

The message stream targeted is archived and cannot be used to send messages. Either unarchive it or use another message stream.

message_stream_cannot_be_modified

The message stream cannot be updated or deleted. Usually applies for default transactional streams.

message_suppression_not_found

The target message suppression could not be found.

message_suppression_cannot_be_modified

The message suppression cannot be updated or deleted. See the error detail for more information.

message_template_not_found

The target message template could not be found.

message_template_content_is_invalid

The content of the message template is invalid.

message_template_alias_in_use

The alias is already in use by another message template in the workspace.

messages_limit_exceeded

The total number of messages to be sent exceed the allowed maximum of 1,000. Happens when sending batch messages in which case, check the request to ensure total number of destinations do not exceed the limit.

messages_suppressions_flagged

The message(s) cannot be sent because one of the phone number destinations is suppressed. Either delete the suppression and resubmit the request or remove the flagged destination as described in the error detail.

terminal_configuration_not_found

The target terminal configuration targeted could not be found.

terminal_configuration_cannot_be_modified

The terminal configuration cannot be updated or deleted. See the error detail for more information.

terminal_location_not_found

The target terminal location targeted could not be found.

terminal_location_cannot_be_modified

The terminal location cannot be updated or deleted. See the error detail for more information.

terminal_device_not_found

The target device configuration targeted could not be found.

device_activation_token_invalid

The provided activation token is invalid because it is either malformed or has expired. Check your device for a new one.

device_already_activated

The target device has already been activated. You may need to delete the device in test/live mode before creating it in the desired mode. If you have another workspace, you may want to delete the device from it before you can use it in another workspace.

terminal_device_in_use

The target device is currently in use for another operation. You can check the current_task node of the TerminalDevice to see what the device is currently working on.

terminal_device_offline

The target device is currently offline and cannot be used to process/handoff tasks.

terminal_device_handoff_failed

Handing off a task to the target device failed. See the error detail for more information.

visitor_destination_not_found

The target visitor destination targeted could not be found.

visitor_destination_cannot_be_modified

The visitor destination cannot be updated or deleted. See the error detail for more information.

visitor_not_found

The target visitor targeted could not be found.

visitor_cannot_be_modified

The visitor cannot be updated or deleted. See the error detail for more information.

visit_not_found

The target visit targeted could not be found.

visit_already_started

The visit is already started. Either end the visit or create a new one.

visit_not_started

The visit is not yet started. Certain operations require the visit to be started. For example, you can only end a visit that has been started.

visit_already_ended

The visit is already ended. An ended visit is in terminal state and cannot be ended again.

visit_destination_required

The visit requires a destination to be supplied at entry/start if none was supplied on creation.

webhook_endpoint_not_found

The target webhook endpoint targeted could not be found.