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 Copy
{
"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 Python
JavaScript Copy
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;
}Python Copy
class DimesumError(Exception):
def __init__(self, status: int, code: str, message: str):
super().__init__(message)
self.status, self.code = status, code
def dimesum(method: str, path: str, **kw):
r = session.request(method, f"https://api.dimesum.com{path}" , **kw)
if r.status_code >= 400 :
err = r.json().get("error" , {}) if r.content else {}
raise DimesumError(r.status_code, err.get("code" , "" ), err.get("message" , r.reason))
return r.json() if r.content else None
try :
dimesum("PATCH" , f"/v1/groups/{group_id}/expenses/{expense_id}" , json=edit)
except DimesumError as e:
if e.code == "stale_version" :
... # read the bill again and reapply
elif e.code == "not_editor" :
... # not yours to change in this group
else :
raise
Codes#
Keys and access#
Status Code Meaning What to do 401 unauthenticatedNo Authorization: Bearer … header, or a malformed one. Send the key as a bearer token. 401 api_key_invalidNot a key we know: mistyped, regenerated or deleted. Check the key; make or regenerate one in Me › Profile › Developer . 401 api_key_disabledThe key is switched off. Switch it on in the app. 403 api_key_not_allowedThis route is not on the public API. See what a key can reach . 403 api_key_read_onlyA write with a read-only key. Use a key with the write scope. 403 api_key_requiredPOST /mcp was called without an API key.MCP takes a developer key, not an app session. 404 not_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. 429 rate_limitedToo many requests. Wait for Retry-After and retry; see Rate limits .
Requests#
Status Code Meaning What to do 400 bad_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. 400 invalid_cursorA cursor that did not come from next_cursor. Pass cursors back unchanged. 405 method_not_allowedThat method is not defined on this path. Check the reference . 413 body_too_largeThe body is over the size limit. Send less. 415 unsupported_media_typeA write without Content-Type: application/json. Set the header.
Bills, comments and repeats#
Status Code Meaning What to do 400 invalid_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. 400 unsupported_split_typeA split_type the server does not know. Use EQUAL, EXACT, PERCENT or SHARES. 400 invalid_fx_rateThe rate is not a positive decimal. Send it as a string such as "0.5624". 403 not_editorIt is somebody else's bill and the group's editor policy does not include you. Check can_edit before offering an edit. 403 read_onlyThe group or the bill is read-only . Do not write to it. 409 idempotency_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. 409 stale_versionSomebody changed the bill after you read it. Read it again, reapply your change, send with the new base_version. 409 expense_deletedThe bill is deleted. Nothing to edit. 400 invalid_commentEmpty or too long (1,000 characters). Fix the text. 429 too_many_commentsThe bill has 200 comments. Start a new thread elsewhere. 429 comment_rate_limited30 comments in an hour from you. Wait a while. 400 invalid_recurring_ruleA repeat with an unknown freq, no amount or no description. The message names the field. Fix the named field.
Groups and members#
Status Code Meaning What to do 400 invalid_nameThe name has characters that cannot be shown. Letters, numbers and spaces work. 400 invalid_timezoneNot an IANA time zone. Use a name such as Asia/Kolkata. 400 invalid_email, invalid_phoneA kept place's email or phone (E.164) does not parse. Fix it or leave it out. 400 group_fullThe group has 50 members. 409 already_memberThat account is already in the group. 429 too_many_groupsYou are in the maximum number of groups.
Payments#
Status Code Meaning What to do 400 overpayA 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. 400 invalid_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. 403 self_confirmThe payer tried to confirm their own payment. The person paid confirms it. 409 wrong_stateThe payment is not in a state that allows this (already confirmed or reversed). Read it again. 409 member_leftSomebody named on it has left the group.
Captures and suggestions#
Status Code Meaning What to do 400 invalid_captureEmpty text or more than 2,000 characters. 400 incomplete_draftConfirming a suggestion with no name or no amount. The message names the field. Send it in the confirm body. 409 not_pendingThe suggestion was already confirmed or dismissed. Nothing to do; confirming twice is a replay only for the same suggestion. 503 parser_unconfiguredThe server has no parser to read text with. Current servers file the capture unread instead (see captures ); handle both.
Rates and the server#
Status Code Meaning What to do 404 fx_currency_unknownThe rate source does not publish that currency. Agree a rate in your group instead. 503 fx_quotes_unavailableMarket rates are not available on this server. Try later, or set the rate yourself. 500 internalSomething broke on our side. Retry with backoff; writes are safe to retry with the same id. 503 not_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 .