API docs / How it works

Errors

Every error returns the same JSON shape, with a stable code you can act on.

Error shape

{
  "error": "validation_failed",
  "message": "This member has no hourly rate, so time can't be converted to slices. Set one in Equity Matrix first.",
  "fields": [
    { "field": "memberEmail", "message": "This member has no hourly rate, so time can't be converted to slices. Set one in Equity Matrix first." }
  ]
}

error is a stable code. message is written for people and may change. fields only appears on validation errors.

Error codes

StatuserrorWhat it meansWhat to do
400invalid_jsonThe body isn’t valid JSONFix the request
401invalid_api_keyThe key is missing, unknown or revokedCheck the key, or create a new one
402plan_inactiveYour Equity Matrix plan isn’t activeReactivate the plan; keys start working again on their own
404not_foundThe contribution doesn’t exist, was deleted, or belongs to another organization. Also returned for a path or HTTP method the API doesn’t haveFor deletes, treat it as done. Otherwise check the path and method against the API reference
409conflictAnother request created a contribution with the same externalId at the same momentRetry once
415unsupported_media_typeThe body isn’t sent as application/jsonSend Content-Type: application/json
422validation_failedA field is missing or invalidFix the fields listed in fields
429rate_limitedToo many requests, or too many rejected keys from your addressWait the number of seconds in Retry-After, then retry
500internal_errorSomething went wrong on our sideRetry later

Common validation errors

  • Both or neither of memberId and memberEmail were sent.
  • The member can’t be found, is INACTIVE, or more than one member has that email.
  • date is missing, isn’t a real date as YYYY-MM-DD, or is in the future.
  • type isn’t one of TIME, CASH, COMMISSION, ROYALTY or CUSTOM.
  • contributionTypeId was sent with a built-in type, or type is CUSTOM without a contributionTypeId.
  • contributionTypeId isn’t one of your organization’s custom types, or that type is turned off.
  • type is DEPOSIT or EXPENSE. Deposits and expenses can only be logged in the app.
  • TIME for a member with no hourly rate.
  • value is 0 or less, or has more than 2 decimal places.
  • description is over 500 characters.
  • externalId is over 100 characters, or uses characters other than letters, numbers and . _ : -.