API Error Codes

The Form Tools API functions use error codes to identify all the possible problems that may crop up. At a later date, the content of this page will be translated - but for now, you're stuck with the English. Apologies to our non-English speaking friends.

Errors are grouped in two categories: user errors, which occur when the information fed to one of the functions is incorrect, and system errors which should never occur, and possibly indicate a Form Tools bug. Most likely, however, system errors are caused by Form Tools files not existing on your server or somehow got corrupted when being sent via FTP to your site.

The numbering scheme for the error codes is purely internal - they have no special meaning. These error codes have nothing to do with the HTML error codes, like "404 not found".

form Integration

Error Code	Type	Explanation
100	User	This occurs when trying to initialize a form. It usually means you're sending along an incorrect form ID. If you're NOT trying to initialize a form, then you're still passing along the form_tools_initialize_form hidden field in your form for "direct" submission page - or you have the second parameter of the ft_api_init_form_page set to "initialize" if you're submitting the information via PHP.
101	User	This occurs when the form has already been marked as "complete" through the Form Tools interface, but you are still trying to send the test submission. This often means that you've simply forgotten to perform the final step: go to "live" mode. For "direct" submissions, you haven't removed the form_tools_initialize_form hidden field. For submissions via the API, there are two likely causes: you're passing along the wrong form ID (check it's not in a hidden field - this is a common pitfall if you're upgrading an old Form Tools form) you haven't removed the second parameter of the ft_api_init_form_page function on your first form page for a form that HAS been set up. For the latter, clear your sessions (see the ft_api_clear_form_sessions function) and try putting through another submission.
102	System	The database query to add the submission ID system field failed. This should not occur; please post in our forums.
103	System	The database query to insert one of your test submission fields failed.
104	System	The database query to insert one the files in your test submission fields failed.
105	System	The database query to insert the submission date, last modified date and IP address failed.
200	User	This error occurs when the ft_api_init_form_page function is passed an invalid value for the second parameter. The second parameter contains the mode: it should any of the following string values: "test", "initialize" or "live". Alternatively, you can omit the parameter altogether - which is the same as "live".
300	User	This occurs when ft_api_process_form doesn't receive BOTH the form ID and the submission ID. These values are not passed to the function explicitly; they are set by ft_api_init_form_page - which should ALWAYS be called prior to ft_api_process_form on every one of your form pages.
301	User	The form ID doesn't exist. Here, the function is trying to put through a live submission (i.e. non-test/initialize). Most likely, you passed the wrong form ID value to ft_api_init_form_page(). Note: the (invalid) form ID is cached. Try emptying sessions using ft_api_clear_form_sessions(), update the form ID and try putting through another submission.
302	User	The submission is already finalized! The ft_api_process_form only processes submissions that aren't finalized. You need to confirm that you are only finalizing the submission on the FINAL step of your form. See the documentation on ft_api_process_form form more information.
303	User	The form has been disabled. Disabling the form is simply a technique to prevent new submissions being registered in the database. You must prevent users from getting to your form by redirecting them, or by removing the link to the form.
304	System	The database UPDATE function failed, when trying to add your form's / form page's submission data. This should never occur, but has been known to with form Tools 1.x. If this occurs, please post in our forums with the full debugging message that appears on screen and we'll help resolve the problem.
305	User	This occurs when the unfinalized submission being processed in a multi-page form no longer exists, but the person hasn't finished putting it through. This should only occur if the database record has been deleted - probably with ft_api_delete_unfinalized_submissions. It's strongly recommended that you don't pass the second parameter to the function so that only older unfinalized submissions that are no longer needed are actually deleted.
306	User	The "form_data" parameter must ALWAYS be passed to the ft_api_process_form function - even if it's empty. This is usually the $_POST value. See the function more information.

Submissions

Error Code	Type	Explanation
400	User	The Export Manager module is not installed or enabled in your Form Tools installation. Go to the modules page to install / enable it.
401	User	The form ID passed to the ft_api_show_submissions function is invalid.
402	User	The View ID passed to the ft_api_show_submissions function is invalid.
403	User	The Export Type ID passed to the ft_api_show_submissions function is invalid.
404	User	The value passed for the "pagination_location" to the ft_api_show_submissions is incorrect. The valid values are "both", "top", "bottom" and "none".
405	User	The form ID parameter (First) passed to the ft_api_get_submission is invalid.
406	User	The submission ID parameter (second) passed to the ft_api_get_submission is invalid.

Other

Error Code	Type	Explanation
500	User	The form ID passed to the ft_api_create_blank_submission function is invalid.
501	User	The default values passed to the ft_api_create_blank_submission function are invalid. Most likely, you've misspelled one of the database column names or included one that doesn't exist.
550	User	The form ID passed to the ft_api_submission_is_unique function is invalid.
551	User	The second $criteria parameter passed to the ft_api_submission_is_unique function is invalid - it needs to be a function.
552	User	The second $criteria parameter passed to the ft_api_submission_is_unique function is invalid - it needs to be a hash.
553	User	The second $criteria parameter passed to the ft_api_submission_is_unique function is invalid - it needs to be an associative array (hash) where the keys are the form table column names and the values are the values you are checking to uniquely identify the record.
554	User	This means the generated SQL query to test for uniqueness failed. The most likely reason for this is that one or more of the criteria you've specified has an invalid database column name; in other words, one of the keys is invalid. Note that the criteria keys should be the database column names (found on your Edit Form » Database tab) and not the form field names.
600	User	The public and/or private recaptcha field key hasn't been set in your api.php file. For more information, read the instructions on the ft_api_display_captcha page.
650	User	The form ID passed to the ft_api_delete_unfinalized_submissions function is invalid.

User Accounts

Error Code	Type	Explanation
700	User	The ft_api_create_client_account function didn't receive the "first_name" key.
701	User	The ft_api_create_client_account function didn't receive the "last_name" key.
702	User	The ft_api_create_client_account function didn't receive the "email" key.
703	User	The ft_api_create_client_account function received an invalid email address in the "email" key.
704	User	The ft_api_create_client_account function didn't receive the "username" key.
705	User	The ft_api_create_client_account function requires the "username" key only contains alphanumeric characters.
706	User	The ft_api_create_client_account function received an invalid value the "username" key. This usually means the username is already taken.
707	User	The ft_api_create_client_account function didn't receive a value in the "password" key.
708	User	The ft_api_create_client_account function requires the "password" key only contains alphanumeric characters.
709	User	The database INSERT query in the ft_api_create_client_account query failed. Most likely, you're passing invalid values for one of the optional keys.
800	User	The account ID passed to ft_api_delete_client_account was invalid.
801	User	The account ID passed to ft_api_delete_client_account was not a client account.
900	User	The account ID passed to ft_api_update_client_account was invalid.
901	User	The account ID passed to ft_api_update_client_account was not a client account.
902	User	The update query in ft_api_update_client_account failed. This is usually due to one or more invalid values being passed to it. Try enabling $g_api_debug and put through the query through your web browser. When the function fails, it will display the failed query in the debugging section.
1000	User	The password field wasn't sent to the ft_api_login function, or it was empty.
1001	User	The login failed; the account has been disabled.
1002	User	The login failed; the account is still pending.
1003	User	The login failed; the password was incorrect.
1004	User	The login failed; the account was not found. This just means the username was incorrect.