Responses and errors

Every API response comes in the same envelope. That lets a single handler serve every call.

#Success

{
  "success": true,
  "message": "Login successful.",
  "data": { },
  "pagination": { "page": 1, "limit": 20, "total": 137, "totalPages": 7 }
}

pagination only appears in lists. See Pagination.

#Error

{
  "success": false,
  "message": "Valid email is required",
  "errors": [{ "param": "email", "message": "Valid email is required" }]
}

• The errors array always comes back, even with a single error.
• param says which field caused the error, when there is one.
• message is the message to show.
• code, when present, is a stable identifier to handle in code (like the API key errors); the message changes with the language, the code doesn't.

This way, validation and business rules are handled the same way: show errors[].message next to the param field; without a param, show it at the top.

#The two kinds of error

#Status codes

#Real examples

Errors for product kinds, free products, seats, Downloads and hosted media:

Going over the plan's storage refuses only new uploads: asking for the upload URL returns 409 storageLimitReached, in media, Downloads and lessons; what's already stored stays. The month's upload volume only warns. See Plan and extensions.

hosted media. A file type outside the list, a size over the limit (500 MB or 50 MB), a size that does not match, content that does not match the format, or a lesson that is neither video nor file: 400; the lesson's file changed during the upload: 409; reading the media without being enrolled, with the lesson locked or the course unpublished: 403, with no URL; a lesson with no hosted file: 404; a member, moderator or finance trying to upload or remove: 403; storage unavailable: 503. Going over the storage limit is never an error: the upload continues and the response carries a warning.

quiz.maxAttempts (1 to 100; empty = unlimited) when creating and editing the quiz lesson, and certificateMinGrade (0 to 100) on the course. The attempt returns maxAttempts, attemptsUsed, attemptsLeft, bestScorePercent and closedWithoutPassing; an attempt after they run out: 409. The course returns userFinalGrade to the student and finalGrade in the student list; below the minimum grade, userCertificate.status is BELOW_MIN_GRADE, with finalGrade and minGrade.

quiz and campaigns. POST /api/courses/lesson and PUT /api/courses/lesson/{lessonId} accept the quiz block (passPercent 1 to 100, 1 to 30 questions, 2 to 6 options with exactly one isCorrect, optional explanation), owner and admin only; a format error: 400, with errors[].param on the field (for example quiz.questions[0].options); changing the type of a quiz with attempts: 409. POST /api/courses/{courseId}/lesson/{lessonId}/quiz/attempts sends the answers (all of them) and returns the score, passed and, only when passed, the correct answers; more than 30 attempts per hour on the lesson: 429, with Retry-After; GET on the same route lists the last 10. POST .../progress with completed: true on a quiz lesson: 409. Campaigns: POST /api/campaigns/{id}/schedule (scheduleKind DAILY or WEEKLY, timeOfDay, weekdays; a past or invalid time: 422 on sendAt), POST .../pause, .../resume and .../cancel (owner and admin only), GET .../runs, GET .../report and GET .../preview (team), GET /api/campaigns/automatic and PUT /api/campaigns/automatic/{systemKey} (turning on requires consent), POST /api/upload/campaigns/image and DELETE (the image of a campaign that left draft: 409). An audience over 500 people on the community's first send: 422; a fixed item in a block that not everyone sees: 422 on blocks[i]; sending, scheduling, editing or deleting an automatic through the ordinary routes: 409.

course community. POST /api/courses/{courseId}/leave on a completed course: 409; without being enrolled: 404. Course or lesson discussion without being enrolled, or writing without being allowed: 403; writing or reacting in a draft or archived course: 409; replying to a reply, empty text or over 2,000 characters, an invalid reaction: 400, with param on the field; a comment or lesson that does not exist (or belongs to another course): 404. Deleting someone else's comment without being on the team: 403. GET /api/courses/{courseId}/leaderboard with the leaderboard off: 403. An instructor whose profile is not owner, admin, moderator or finance: 400; learningPoints with more than 8 items or an item over 140 characters: 400; a member sending instructorMemberId, learningPoints or leaderboardEnabled: 403.

e-mail campaigns. POST /api/campaigns/{id}/send without consent: true (param: "consent"), an empty subject or content, an invalid block, an empty audience or one over 20,000 people, or an unsubscribed person chosen by hand (param: "audience.memberIds"): 422; a moderator or finance trying to send: 403; a campaign already sent: 409; daily, weekly or monthly quota exhausted: 429, saying the limit and when it frees up, before any e-mail goes out. Editing or deleting a campaign already sent: 409. A campaign from another community: 404.

locked lesson. POST /api/courses/{courseId}/lesson/{lessonId}/progress on a lesson the sequence or a date has not opened yet: 409 · Finish "…" before this lesson. or This module opens on …, with param: "lessonId". The lesson gets no progress or points. A requireSequential that is not true or false: 400; both release fields together, or an invalid date or days: 400, with the message on the field; a member or moderator sending these fields: 403.

events: RSVP and times. POST /api/events/{id}/participate with going or maybe after the end: 409 · This event has already ended. You can no longer confirm attendance., with param: "status" (not_going still works). POST and PUT /api/events with an end equal to or before the start: 400 · End time must be after start time, with param: "endTime". Turning on the event certificate without endTime: 400 · Set an end time to issue a certificate…, with param: "certificate.enabled". Template from another community: 404; archived or deleted template: 400, with param: "certificate.templateId"; text with HTML or too long: 400, with param: "certificate.text". A moderator or member sending the certificate block: 403.

events: draft and publishing. PATCH /api/events/{id} with an updatedAt (or If-Unmodified-Since) older than the last save: 409, with param: "updatedAt" and the current data.updatedAt; nothing changes. POST /api/events/{id}/publish with something missing: 422, one errors[] item per field (title, startTime, endTime, location for in-person or hybrid, ticketTypes) and data.readiness; an event already published: 409. RSVP, ticket purchase, registration, waitlist or streaming on a draft: 409 for the team and 404 for everyone else.

events: who reads. GET /api/events/{identifier} without X-CommunityId: 400. A Members event signed out: 401; signed in without being in the community: 403. An event that does not exist, belongs to another community, or is a draft, private, awaiting moderation or rejected: 404. A plan event or one sold through a paid product, for someone without access, is not an error: 200, with requiresPlan or requiresPurchase set to true and the livestream, recording and address set to null.

workflows: role of whoever saves. Creating, editing, turning on or resuming a workflow with an action above the role of whoever does it (a moderator never saves workflows; an admin acts like the owner, except for an owner-only action, and none exists today; or a called workflow that does something above their role): 422 · workflows.graph.actionAboveRole or subWorkflowAboveRole, on the block. Running one of these now or calling its webhook address: 403 workflows.actionsAboveRole. Deleting a run still under way from the history: 409 · This run is still under way. Stop it before deleting. POST /api/workflows/{id}/simulate with sendEmailsToMe: true: more than 10 in an hour, 429; an account without e-mail, 422 emails.noEmail. PUT /api/vault/ai-limits out of bounds, or with per call above per run or per run above per day: 422.

SMS and WhatsApp. PUT /api/sms/settings or /api/whatsapp/settings turning on without a daily cap: 422, with param: "dailyCap"; outside 1 to 50,000: 422. Turning on a channel the plan doesn't have: 409 · SMS is not available on this community's plan. (on WhatsApp below Business, 403 whatsapp.notOnPlan). personDailyCap outside 1 to 20: 422. POST /api/members/me/phone-verification with SMS off in the community: 409; a phone from a blocked or unknown country (today, the United States on SMS): 422; too many codes in the community on the same day: 429 · This community reached today's code limit. Try again tomorrow.; another code within 1 minute: 429 with Retry-After and data.retryAfterSeconds, and more than 3 an hour or 6 a day for the same phone, 6 a day per account or 10 an hour per IP: 429. .../confirm with the wrong code: 400, with the tries left; expired or with the 5 tries used: 400, ask for another. PUT /api/members/me/notice-preferences turning SMS or WhatsApp on without a verified phone: 409. The tests (POST /api/sms/test, /api/whatsapp/test) never fail on a sending rule: they answer 202 with skipped and the reason (smsPhoneUnverified, whatsappTemplateNotApproved…).

Plan quotas. A campaign whose audience goes over the recipients left in the period: 429 quota_recipients. Reprocessing a video without conversion minutes: 409 transcodeQuotaReached (or transcodeNotOnPlan on Starter). See Plan and extensions.

More examples, in the order you run into them while building something, in Creation order.

#Version conflict

The editors check the version before saving, so one save never wipes out another without warning. Send the version you read in one of these ways:

• updatedAt in the body, with the value the GET returned (on the community row, settingsUpdatedAt);
• or the If-Unmodified-Since header.

If another save came first, the answer is 409, nothing changes, and data carries the current version:

{
  "success": false,
  "message": "Someone else saved this after you opened it. Reload to see the current version and make your change again.",
  "errors": [{ "param": "updatedAt", "message": "…" }],
  "data": { "updatedAt": "2026-10-28T14:05:00.000Z" }
}

Read again and repeat the change, or send the save with the new version to write over it on purpose. Every success answer carries the new version. It is optional: without the field and the header, the save goes as before.

Whoever cannot edit the item gets the usual 403 or 404, never the version. To know right away that someone saved, listen to item.saved in Realtime.

#Chat limits

The chat (Messages) has anti-spam limits per person and per community, for the app, the API and the MCP alike. Going over a limit answers 429 (ChatRateLimited in the reference), with the translated message saying when it frees, in the community's time zone:

{
  "success": false,
  "message": "…",
  "errors": [{ "param": "limit", "message": "…", "code": "limitNewConversationsHourly", "limit": 10, "retryAt": "2026-10-22T18:42:10.000Z" }]
}

limit is the maximum that applies to the caller: half of the request and new-conversation limits for someone who joined less than 24 hours ago, and double every limit for the team (owner, admin, moderator and finance). When time frees it, retryAt (ISO 8601) and the Retry-After header, in seconds, come along. The windows slide: a slot frees when the oldest action in the window completes the period.

#Person name

Each person has one name (see Account and profile › Name). In the API:

• POST /api/members/invite accepts people: [{ email, name }] besides emails (one of the two is enough): the new account is created with the name, and the invitation email goes out with it.
• PUT /api/members/{id} accepts name (the older displayName still works) and PUT /api/members/me accepts only name. The name changes only in this community; on someone else's, the display name changes, and the full name only in the provisional-name case.
• The responses of GET and PUT /api/members/{id}, GET /api/members and PUT /api/members/me include name, the name that's shown.
• Sending the same name that's already shown changes nothing and skips the rules below.

#Stock

A one-off product with hasStock has stockQuantity, the number available right now.

The unit is reserved on the order and comes back only once (payment declined, PIX or boleto expired, a refund that revokes access). The direct-link catalog, GET /api/checkout/products, returns soldOut (true or false, without the quantity), like the Store. The management routes (GET /api/products and GET /api/products/{idOrSlug}) return stockQuantity to the owner, the admin and finance; other roles get only the active products, with soldOut.

#Appearance and themes

The community's appearance is written only through themes (/api/community-themes, see Theme and colors).

#Payouts and receiving payments

The maximum payout is the smaller of the statement's available amount and the payout account balance, with the amount plus the fee fitting in it. To avoid a refusal, read GET /api/payouts/balance first: withdrawableBalance is the balance you can pay out, transferFee the fee and maxPayoutAmount the largest amount you can request. Refunds waiting for balance also come out of what can be paid out: pendingRefunds says how much is reserved for them. An accepted request answers 201 with the payout in the state it ended in: PROCESSING when it was sent to the bank, FAILED when it was refused right away. See Payouts. minPayoutAmount is the smallest amount accepted. Only available counts towards what can be paid out: pending (sales before their release date) and retained (the chargeback reserve) never do. With a balance in more than one currency, balances[] has one line per currency, and ?currency= picks the currency of the answer.

Memberfy team routes. Two SuperAdmin routes follow payouts and, like every /api/admin route, stay out of the public reference: GET /api/admin/payouts lists the payouts of every community (filters communityId, status, from and to), and POST /api/admin/payouts/{payoutId}/retry retries a failed payout as a new payout, linked to the previous one, only once. Retrying a payout that didn't fail, or that was already retried, answers 409. For the community, the new payout shows up in GET /api/payouts like any other.

#Refund

Three routes, all through the X-CommunityId community, for owner, admin and finance (moderator and member: 403; a purchase from another community: 404):

Besides the amount, the platform fee and the net (netAmount), each sale carries refundedAmount (what has already been refunded or is on its way), refundableAmount (what still can be), refundMethod (PROVIDER: Memberfy gives it back through the card or PIX; SETTLED_OUTSIDE: boleto, the community returns it directly), lastRefund and refundBlockedReason, with the translated sentence in refundBlockedMessage, when the purchase can't be refunded through Memberfy yet:

Read refundBlockedReason before offering the refund: the POST refuses these purchases with the same message. On card and PIX, a refund can be partial, from 0.01 up to refundableAmount (partialRefundAvailable is always true), and in an order with several purchases (a plan and its add-ons) each purchase is refunded on its own. A partial one usually comes back as PENDING until the provider confirms it.

Status and timeline. Every sale carries situation, the same word as the Status column and filter of the Sales tab: PAID, PROCESSING, AWAITING_BALANCE, REFUNDED, PARTIALLY_REFUNDED, SETTLED_OUTSIDE, IN_REVIEW, DECLINED, DISPUTED, AWAITING_PAYMENT and FAILED. The detail also carries timeline, the sale's timeline, oldest first. Each event has type, at (the date; future: true on a date that hasn't come yet, such as a release), actor (BUYER, STAFF with name and role, MEMBERFY, PROVIDER or SYSTEM, with label already translated), amount, currency, params and text, the event already translated by Accept-Language. The type values:

The timeline never carries provider cost or provider ids.

The POST body: access (KEEP keeps access; REVOKE removes access and, on a subscription, cancels the subscription right away), idempotencyKey (required: generate one when opening the dialog and resend the same one on retries), amount (default: what is left to refund), reason and, on boleto only, settledOutside (at and note), which records the money returned directly by the community.

The response is the refund (PurchaseRefund): 201 when it is new, 200 on a repeat with the same key, never a second refund. status says where it stands: SUCCEEDED (done), PENDING (the provider still has to confirm), AWAITING_BALANCE (no balance in the receiving account for the community's part: it goes out on its own, in order of arrival, and the access choice already applies), DECLINED (declined, with failureReason) or NEEDS_REVIEW (under review: Memberfy reviews it and completes or declines it). It also carries accessDecision, source (MEMBERFY, or PROVIDER when it was made outside Memberfy), communityAmount (what left the community's balance) and platformFeeReturned (the platform fee returned).

On card and PIX, the statement debits only the community's part (communityAmount), and the platform fee goes back in proportion. On a boleto returned directly, communityAmount and platformFeeReturned are zero. A purchase refunded with KEEP stays COMPLETED and active; the refund shows in refundedAmount and lastRefund. For the buyer, GET /api/purchases/me returns refundedAmount, refundedAt and refunds; on a subscription, each charge in GET /api/manage/subscriptions/{subscriptionId} carries the purchaseId the refund needs. See Refunds and disputes.

Memberfy team route. GET /api/admin/refunds (SuperAdmin only, out of the public reference) lists the refunds of every community; ?status=NEEDS_REVIEW are the ones under review, which Memberfy completes or declines.

#Plan change

POST /api/subscriptions/{id}/change-tier charges the card, so it accepts an idempotency key: idempotencyKey in the body or the Idempotency-Key header, 8 to 100 characters (A-Z, a-z, 0-9, _, ., : and -). Generate one per attempt by the person (for example, when they confirm a combination of plan and add-ons) and resend the same one on retries, such as after a timeout.

Two changes at the same time on the same subscription (two tabs, the app and the assistant) never charge twice: one goes through, the other gets the 409. The same rule applies to the preview and to the change with addOnProductIds (the add-ons in the same charge) and with cardToken (a new card, which becomes the subscription's card when the charge goes through). The route does not accept an API key. See Change plan.

#PIX and boleto

POST /api/subscriptions/{id}/change-tier takes paymentMethod: CREDIT_CARD (the default), PIX or BOLETO, one of the preview's allowedMethods.

The amount is the prorated one calculated when the order is created and doesn't change until it is paid. On confirmation, if the subscription is no longer on the option and period the order was priced for, or the target or an add-on is no longer valid, the payment is refunded and nothing changes. Expired or canceled order: nothing changes and the subscription is free again; a PIX paid after it expired is refunded. The same idempotencyKey while the order waits returns the same payment data (replayed = true, mode = PENDING_PAYMENT).

#Undoing is DELETE

Taking back a reaction or removing an event recording uses the DELETE method, on the same path used to add it. POST only adds or changes: sending the same reaction again no longer takes it back.

Clearing a field inside an edit (the event banner or highlight, for example) is still a PUT with the field empty, and state changes (cancel, archive, decline, pin to the feed, leave a course) keep their own routes.

#API key errors

With the X-Api-Key header (see Authentication › API key), the key's refusals carry a code in errors[0]:

A key that is invalid, revoked, expired, from another community or belongs to someone who left the community gets 401, with no code, and the reason in the message ("This API key was revoked.").

{
  "success": false,
  "message": "This action does not accept an API key.",
  "errors": [{ "param": "X-Api-Key", "message": "This action does not accept an API key.", "code": "API_KEY_BLOCKED" }]
}

#Language of messages

Messages come in the language of the Accept-Language header (pt-BR, en-US, es-ES, it-IT, de-DE and the other variants). Without a recognized language, they come in English. This also holds for authentication and role errors (401 and 403), which use the same envelope, with errors[].

#Item from another community

An item that belongs to another community answers 404, the same as an id that doesn't exist. The API doesn't reveal that the item exists elsewhere: for the caller, it doesn't exist in the X-CommunityId community.

Being an owner, admin or moderator in one community gives no access to anything in another, even when sending your own community's header. If the item is from the community and still answers 404, check that X-CommunityId is the right community.

#Deleted items

The API doesn't truly delete: deleted items are marked as removed and stop showing up. That's why a deleted id answers 404, as if it never existed.

#With the SDK

The SDK throws a MemberfyError with .status, .body (the whole envelope) and .errors. See JavaScript SDK.

#AI assistant turned off

If the owner turned off the AI assistant for your role, OAuth authorization answers 403 with "The owner has turned off the AI assistant for your role in this community…", and /mcp refuses every call with "The owner of {community} has turned off the AI assistant for {group}. Talk to the community owner to turn access back on." Anyone who tries to change the switches without being the owner gets 403; a value that is not a boolean, 400. See Authentication.

#Related

• Authentication
• X-CommunityId
• Creation order