Table of contents
- API Usage Guide
- API Command Reference
- add_booking
- add_client
- add_invoice
- add_resource
- approve_request
- authenticate_user
- del_booking
- del_bookings
- del_client
- del_invoice
- del_resource
- email_client
- gen_invoice
- get_activity
- get_availability
- get_booking
- get_booking_type
- get_booking_types
- get_bookings
- get_client
- get_consumable_levels
- get_invoice
- get_invoices
- get_messages
- get_reminders
- get_resource
- get_resource_availability
- get_setting
- get_template
- get_user
- get_users_logged_in
- get_venue
- get_venues
- get_venues_in_group
- get_venues_in_use
- get_watches
- mod_booking
- mod_client
- mod_invoice
- mod_resource
- mod_venue
- notify_user
- reject_request
- restore_booking
- set_setting
- set_template
- util_api_usage
- util_from_epoch
- util_to_epoch
- Appendix A - Activity Codes
- Appendix B - Setting Names
- Appendix C - Error Handling
- Code Samples
- C#
- Java
- jQuery
- .NET
- Perl
- PHP
- Python
- Ruby
- Troubleshooting
- Release Notes
MIDAS API: Appendix C - Error Handling
MIDAS API: Appendix C - Error Handling
When making API calls, your applications should take into account possible errors that may be returned.
Unless you've configured your API to return http status code 200 (OK) for every request, successful API calls should return either a 200 (OK) or 201 (Created) http status code. Unsuccessful API calls may return 4xx/5xx http status codes, as outlined in the Error Response table below.
API errors themselves are returned in JSON format.
| Example Error Response |
{"error":"error response"} |
| Error Response | HTTP Status Code | Meaning | Applies To |
| "API running in read only mode" | 403 | The API is currently running in read-only mode, and you have made a call that requires full-access. Read-Only mode can be turned off via MIDAS Admin Options → Manage Addons → API Access → Read-Only access | add_* |
| "booking not found" | 404 | The specified booking was not found | del_booking |
| "client not found" | 404 | The specified client was not found | email_client |
| "exceeds invoice total" | 400 | The sum of amounts paid, credited, and refunded exceed the specified invoice's total | mod_invoice |
| "filter field not found" | 400 | The specified filter field is invalid | get_bookings |
| "GET method not allowed. Use POST instead" | 405 | An http GET request has been made to the API, but the API has been set to accept http POST requests only. This setting may be changed via MIDAS Admin Options → Manage Addons → API Access → Allow GET (as well as POST) method | All |
| "invalid api key" | 401 | The API key supplied is invalid. See also API Troubleshooting | All |
| "invoice x is already associated with this booking" | 409 | An attempt was made to generate an invoice for a booking which already has an invoice associated with it | gen_invoice |
| "invoice not found" | 404 | The specified invoice was not found | del_invoice |
| "missing api key" | 401 | You have not supplied your API key in your call. See also API Troubleshooting | All |
| "no email address on record" | 400 | The specified client record has no email address associated with it | email_client |
| "no matches found" | 404 | No data was returned for the API call. Try broadening the search parameters | del_bookings |
| "not available with LDAP enabled" | 400 | The API call is unavailable when Active Directory sign-on in enabled | authenticate_user |
| "not enabled" | 503 | API access is not enabled at this time. API access can be enabled from within MIDAS via MIDAS Admin Options → Manage Addons → API Access → Enabled | All |
| "notification expired" | 400 | The notification's expiry date/time has passed | notify_user |
| "protected setting" | 401 | The setting you're trying to modify is read-only and cannot be modified | set_setting |
| "referrer not allowed" | 403 | The API call originates from a blocked domain/IP address. Allowed domains/IP's may be specified from within MIDAS via MIDAS Admin Options → Manage Addons → API Access → Allowed Referrers | All |
| "required parameter missing" | 400 | One or more parameters are required for the particular call you're making is missing | All |
| "required permission missing" | 401 | The API call was made under a user account which does not have sufficient privileges to make the particular API call | Various |
| "request not found" | 404 | The specified booking resource was not found | approve_request |
| "resource not found" | 404 | The specified resource was not found | del_resource |
| "unable to ..." | 502 | A generic error indicated that the API has behaved in an unexpected way. Please contact our support team for assistance | Various |
| "unable to connect to database" | 503 | The API was unable to connect to the database | All |
| "unable to delete - invoice not yet paid" | 401 | Software settings prevent the specified invoice from being deleted until it has been paid in full | del_invoice |
| "unable to modify - invoice has been sent" | 401 | Software settings prevent the specified invoice from being modified once it has been finalized | mod_invoice |
| "unknown booking type" | 404 | Indicates that the specified booking type doesn't exist | get_bookings (when the type parameter is specified) |
| "unknown command" | 400 | The API command you've specified was unrecognized. Please check you're using a valid command | All |
| "unknown resource" | 404 | Indicates that the specified resource doesn't exist | get_resource |
| "unknown setting" | 404 | Indicates that the specified setting isn't recognized | get_setting |
| "unknown template" | 404 | Indicates that the specified template isn't recognized | get_template |
| "unknown user" | 404 | Indicates that the specified user doesn't exist | get_activity |
| "unknown venue group" | 404 | Indicates that the specified venue group doesn't exist | get_venues_in_group |
| "unknown venue" | 404 | Indicates that the specified venue doesn't exist | get_availability (when the venue parameter is specified)get_venue |