Skip to main content

Error codes

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, there are three status code ranges to expect:

  • 2xx success status code confirm that a request worked as expected.
  • 4xx error status codes indicate and 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, these type of 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. This happens when the workspace has been suspended due to billing issues. It can also happen if the workspace has be 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 the relevant lack information required to support the request.

idempotency_error​

Idempotency cannot be performed on this request. This is usually because 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. This occurs if your 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 thus cannot be updated.

object_redaction_in_progress​

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

identity_verification_not_found​

The target identity verification could not be found.

identity_verification_cannot_be_modified​

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

identity_verification_cannot_be_cancelled​

The identity verification cannot be cancelled. This happens when status is not input_required. You should wait for processing to complete or to fail and return to the input_required state.

identity_verification_cannot_be_redacted​

The identity verification cannot be redacted. This happens when status is not input_required or verified. You should 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 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 create does not allow downloading or creation of unauthenticated links.

The target file link could not be found.

The target file link cannot be updated. This happens when the file link has already expired. You should instead 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_ongoing_for_target​

The payment cannot be created/initiated because there is another payment for the same type targeted at the same customer in your workspaces that is still pending. You should wait for the pending one to either fail or succeed before trying again.

payment_authorization_not_found​

The target payment authorization could not be found.

payment_authorization_closed​

The payment authorization has already been closed 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. This happens when status is not accepted indicating the messages has already been sent or is currently being sent.

message_cannot_be_redacted​

The message cannot be redacted. This happens when status is sending. You should wait for sending to complete or to fail.

message_media_invalid​

The media for the message is invalid. This 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. This happens when status is not accepted indicating the messages has already been sent or is currently being sent.

message_batch_cannot_be_redacted​

The message batch cannot be redacted. This happens when status is sending. You should wait for sending to complete or to fail.

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 this 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. This happens when sending batch messages in which case, you should check your 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.

webhook_endpoint_not_found​

The target webhook endpoint targeted could not be found.

Last updated on