Errors


When a request fails, success is false and an errors list says what went wrong. The HTTP status is never 200. Check success on every response before you treat a record as saved.

Failed response
			
{
  "success": false,
  "errors": [
    "Unable to find record"
  ]
}


		

HTTP status codes

  • 400 The request was rejected. Most failures use this status: a missing or invalid field, a record that does not exist, or a rule the data breaks. Fix the request before you send it again.
  • 401 The token is missing or cannot be read. See Authentication.
  • 403 The token is valid but is not allowed to do this, or API access is not turned on for the site.
  • 413 The request body is larger than 1 MB.
  • 422 An Add/Update endpoint refused data that can never be accepted as sent, so sending it again will fail the same way.
  • 429 You sent too many requests. See Rate Limits.
  • 503 On an Add/Update endpoint, another request was updating the same record at the same moment. Wait a few seconds and send the same request again.
  • 500 Something went wrong on our side. Try again, and contact support if it keeps happening.

Error codes

Most entries in errors are plain messages. A few are objects with a code you can match on instead of the text, and data that describes the record involved.

Error with a code
			
{
  "success": false,
  "errors": [
    {
      "code": "record_not_found",
      "data": {
        "modelName": "Customer",
        "externalId": "CUST-1001"
      }
    }
  ]
}


		
  • record_not_found A record you referred to does not exist on this site. Check the id you sent, or create the record first.
  • record_locked Another request is updating the same record. The status is 503 on Add/Update endpoints and 400 on the others. Either way, sending the same request again after a short wait is safe.

Records to send first

When a request refers to a record that has to exist first, such as the parent of a customer, the response can include a missingRecords list. Each entry names the kind of record and the id you used for it. Create those records, then send the original request again.

Response with missing records
			
{
  "success": false,
  "errors": [
    {
      "code": "record_not_found",
      "data": {
        "modelName": "Customer",
        "externalId": "PARENT-1001"
      }
    }
  ],
  "missingRecords": [
    {
      "model": "Customer",
      "externalId": "PARENT-1001"
    }
  ]
}


		

Common errors

The messages below are quoted exactly, so you can search this page for the text you received.

  • Feature integrations.hyfin_api_access is not available for Site {site_id} API access is not turned on for this site. Contact support to have it turned on. The message ends with the site's id.
  • Unable to find record No record with that id exists on this site, or the record was deleted.
  • Missing required field A required field is empty or missing. The message names the field.
  • Invalid totals.subtotal Invalid totals.total The totals you sent do not match the invoice lines. The message shows the amount expected and the amount received.
  • Invoice has been paid and cannot be deactivated The invoice has a payment taken through the app, so it cannot be deleted. See Deleting Records.
  • Invoice is deleted, will not resend. A deleted invoice cannot be sent again.
  • You have hit the throttle limit for this payment, please try again in a minute The same payment was requested again within a minute.
  • Request body too large The request body is over 1 MB. Send fewer records in each request.