If you try to access an object that does not exists the API responds with the HTTP error code 404. When trying to access an object without the necessary rights you will get an HTTP error code 403 in return.
If another error occurs the API responds with an HTTP status 400 and the following JSON format:
{
"errors":[
{
"field":"name",
"code":"already_exists",
"message":"A tag with this name already exists."
}
]
}Please note that there can be more than one error (example with a german localisation):
{
"errors":[
{
"field":"foo",
"code":"invalid",
"message":"Ungültig"
},
{
"field":"bar",
"code":"required",
"message":"Pflichtfeld"
}
]
}An error always specifies the associated field. If the error doesn’t belong to a specific field (like “invalid_json”) the field value is “global_error”.
{
"errors":[
{
"field":"global_error",
"code":"invalid_json",
"message":""
}
]
}Furthermore an error gives you an error code, which is a constant lower case string whose meaning is explained in the table below.
Some errors may provide an user message, too. This is a human readable localised error message translated to the language the user has chosen in the FundraisingBox. Pay attention that not every error provides such a human readable message. Generally speaking these errors without a human readable message points to a programming error. This case is neither caused by a user nor can be fixed by a user.
Code | User message | Description |
|---|---|---|
address_incomplete | yes | the provided address is incomplete. At least one value (post code, city, etc.) is missing. |
already_exists | yes | an object (e.g. a tag) that should be created exists already |
already_used | yes |
|
bank_account_incomplete | yes | the provided bank account is incomplete. At least one value (IBAN, bank account number, etc.) is missing |
conflicting_data | yes | some data is inconsistence |
date_must_be_future | yes | a date must be in the future |
date_must_be_past | yes | a date must be in the past |
donations_exist | yes | the requested operation is not possible since there is at least one connected donation |
donations_or_recurrings_exist | yes | the requested operation is not possible since there is at least one connected donation or recurring payment |
fundraising_pages_exist | yes | the requested operation is not possible since there is at least one connected fundraising page |
has_receipt | yes | a donation with an existing donation receipt could not be deleted |
invalid | yes | the specified value is invalid |
invalid_api_version | no | the url references to an invalid api version (only exists for the field “global_error”) |
invalid_json | no | the provided data is not a valid json document (only exists for the field “global_error”) |
invalid_is_main_status | no | there must be exactly one address/email address/phone/bank account per person where is_main is true. |
max | yes | the specified text is too high |
max_length | yes | the specified text is too long |
min | yes | the specified value is too low |
min_length | yes | the specified text is too short |
missing_api_version | no | there is no api version specified in the URL path (e.g. https://secure.fundraisingbox.com/donations.json instead of https://secure.fundraisingbox.com/v1/donations.json) |
missing_id | no | an required id is missing |
missing_sepa_config | no | to use sepa mandates you have to specify some sepa details like creditor id in your FundraisingBox before |
no_api_package | no | this API is part of the api package which is not booked yet |
no_permission | no | the user has no permission to perform this request (e.g. no write permission or crm is not active) |
no_write_operation_available | no | the entity is a readonly object and does not provide the requested write operation (only exists for the field “global_error”) |
no_square_size | yes | an uploaded image must be square |
not_deletable | yes | an object is not deletable (e.g. a bank account is still used in an active recurring payment) |
not_editable | no | the field exists, but is not editable. This is typically caused by the current object state (e.g. you cannot edit the amount of a donation when a donation receipt exists) |
person_on_waitlist | no | the operation is not allowed for a person on the waitlist. |
project_items_exist | yes | an project is not deletable since it is used in at least one form as project item |
quota_exceeded | no | the quota for this object type is exceeded |
recurrings_exist | yes | the requested operation is not possible since there is at least one connected recurring payment |
reference_prefix_invalid | yes | the provided sepa mandate reference must not start with a specific string |
required | yes | a mandatory value is missing |
sepa_mandate_payment_type_mismatch | yes | Either you use a payment type that does not need a SEPA mandate with a mandate or a payment type that need a SEPA mandate does not have one. |
signature_dispensable | yes | a pending sepa mandate cannot have a signature date |
unknown_error | no | an unknown error occured (only exists for the field “global_error”) |
unknown_field | no | the JSON data contains a field that is not part of the JSON schema |
vbpk_exists | yes | with an activated vbPK extension (only used in Austria) a person’s name or birthday cannot be changed when there is a vbPK already |