dimesumdevelopers API reference Console Open the app

Errors

Every refusal has the same shape and a stable code. Switch on the code; the message is a sentence for a person and may change.

The envelope#

JSON
{
  "error": {
    "code": "stale_version",
    "message": "expense changed since it was read"
  }
}
  • code is stable and machine-readable. New codes may appear; treat an unknown one by its HTTP status.
  • message is for people. Show it, log it, never parse it.
  • 2xx is success. 4xx is something to change in the request (or wait for). 5xx is ours.
JavaScript
async function dimesum(path, init = {}) {
  const res = await fetch(`https://api.dimesum.com${path}`, {
    ...init,
    headers: { Authorization: `Bearer ${process.env.DIMESUM_API_KEY}`, "Content-Type": "application/json", ...init.headers },
  });
  const body = res.status === 204 ? null : await res.json();
  if (!res.ok) {
    const err = new Error(body?.error?.message || res.statusText);
    err.status = res.status;
    err.code = body?.error?.code;
    throw err;
  }
  return body;
}

try {
  await dimesum(`/v1/groups/${groupId}/expenses/${expenseId}`, { method: "PATCH", body: JSON.stringify(edit) });
} catch (e) {
  if (e.code === "stale_version") { /* read the bill again and reapply */ }
  else if (e.code === "not_editor") { /* not yours to change in this group */ }
  else throw e;
}

Codes#

Keys and access#

StatusCodeMeaningWhat to do
401unauthenticatedNo Authorization: Bearer … header, or a malformed one.Send the key as a bearer token.
401api_key_invalidNot a key we know: mistyped, regenerated or deleted.Check the key; make or regenerate one in Me › Profile › Developer.
401api_key_disabledThe key is switched off.Switch it on in the app.
403api_key_not_allowedThis route is not on the public API.See what a key can reach.
403api_key_read_onlyA write with a read-only key.Use a key with the write scope.
403api_key_requiredPOST /mcp was called without an API key.MCP takes a developer key, not an app session.
404not_foundIt does not exist, or it is in a group you are not in.Check the id. Not-a-member is deliberately indistinguishable from not-there.
429rate_limitedToo many requests.Wait for Retry-After and retry; see Rate limits.

Requests#

StatusCodeMeaningWhat to do
400bad_requestThe body is not valid JSON, an id is not a UUID, or a query value is out of range. The message names it.Fix the named field.
400invalid_cursorA cursor that did not come from next_cursor.Pass cursors back unchanged.
405method_not_allowedThat method is not defined on this path.Check the reference.
413body_too_largeThe body is over the size limit.Send less.
415unsupported_media_typeA write without Content-Type: application/json.Set the header.

Bills, comments and repeats#

StatusCodeMeaningWhat to do
400invalid_expenseThe bill does not add up or is missing something: payers that do not sum to the amount, an unknown member, an edit without participants and split_type. The message says which.Fix and resend with the same id.
400unsupported_split_typeA split_type the server does not know.Use EQUAL, EXACT, PERCENT or SHARES.
400invalid_fx_rateThe rate is not a positive decimal.Send it as a string such as "0.5624".
403not_editorIt is somebody else's bill and the group's editor policy does not include you.Check can_edit before offering an edit.
403read_onlyThe group or the bill is read-only.Do not write to it.
409idempotency_conflictThis id was already used with different content.Generate a new id for a new write; reuse an id only to retry the identical request.
409stale_versionSomebody changed the bill after you read it.Read it again, reapply your change, send with the new base_version.
409expense_deletedThe bill is deleted.Nothing to edit.
400invalid_commentEmpty or too long (1,000 characters).Fix the text.
429too_many_commentsThe bill has 200 comments.Start a new thread elsewhere.
429comment_rate_limited30 comments in an hour from you.Wait a while.
400invalid_recurring_ruleA repeat with an unknown freq, no amount or no description. The message names the field.Fix the named field.

Groups and members#

StatusCodeMeaningWhat to do
400invalid_nameThe name has characters that cannot be shown.Letters, numbers and spaces work.
400invalid_timezoneNot an IANA time zone.Use a name such as Asia/Kolkata.
400invalid_email, invalid_phoneA kept place's email or phone (E.164) does not parse.Fix it or leave it out.
400group_fullThe group has 50 members.
409already_memberThat account is already in the group.
429too_many_groupsYou are in the maximum number of groups.

Payments#

StatusCodeMeaningWhat to do
400overpayA leg of a payment across groups is more than is owed in its group: a netted leg, or a balance that moved since it was read. Payments themselves may exceed what is owed.Read the balances again and send the payment with fresh figures.
400invalid_settlementThe payment is not valid as sent, for example a zero amount or the same person on both sides.Record from your own my_member_id to somebody else, for more than zero.
403self_confirmThe payer tried to confirm their own payment.The person paid confirms it.
409wrong_stateThe payment is not in a state that allows this (already confirmed or reversed).Read it again.
409member_leftSomebody named on it has left the group.

Captures and suggestions#

StatusCodeMeaningWhat to do
400invalid_captureEmpty text or more than 2,000 characters.
400incomplete_draftConfirming a suggestion with no name or no amount. The message names the field.Send it in the confirm body.
409not_pendingThe suggestion was already confirmed or dismissed.Nothing to do; confirming twice is a replay only for the same suggestion.
503parser_unconfiguredThe server has no parser to read text with.Current servers file the capture unread instead (see captures); handle both.

Rates and the server#

StatusCodeMeaningWhat to do
404fx_currency_unknownThe rate source does not publish that currency.Agree a rate in your group instead.
503fx_quotes_unavailableMarket rates are not available on this server.Try later, or set the rate yourself.
500internalSomething broke on our side.Retry with backoff; writes are safe to retry with the same id.
503not_readyThe server is starting or a dependency is down.Retry with backoff.

Errors inside MCP#

MCP answers are HTTP 200 with a JSON-RPC body. A malformed request is a JSON-RPC error (-32700 not JSON-RPC, -32601 unknown method, -32602 bad params). A tool that the API refused comes back as a normal result with isError: true and the API's envelope in its text, for example HTTP 403: {"error":{"code":"api_key_read_only",…}}. See the MCP guide.