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
| Status | error | What it means | What to do |
|---|---|---|---|
400 | invalid_json | The body isn’t valid JSON | Fix the request |
401 | invalid_api_key | The key is missing, unknown or revoked | Check the key, or create a new one |
402 | plan_inactive | Your Equity Matrix plan isn’t active | Reactivate the plan; keys start working again on their own |
404 | not_found | The contribution doesn’t exist, was deleted, or belongs to another organization. Also returned for a path or HTTP method the API doesn’t have | For deletes, treat it as done. Otherwise check the path and method against the API reference |
409 | conflict | Another request created a contribution with the same externalId at the same moment | Retry once |
415 | unsupported_media_type | The body isn’t sent as application/json | Send Content-Type: application/json |
422 | validation_failed | A field is missing or invalid | Fix the fields listed in fields |
429 | rate_limited | Too many requests, or too many rejected keys from your address | Wait the number of seconds in Retry-After, then retry |
500 | internal_error | Something went wrong on our side | Retry later |
Common validation errors
- Both or neither of
memberIdandmemberEmailwere sent. - The member can’t be found, is
INACTIVE, or more than one member has that email. dateis missing, isn’t a real date asYYYY-MM-DD, or is in the future.typeisn’t one ofTIME,CASH,COMMISSIONorROYALTY.TIMEfor a member with no hourly rate.valueis 0 or less, or has more than 2 decimal places.descriptionis over 500 characters.externalIdis over 100 characters, or uses characters other than letters, numbers and. _ : -.