Specify API rejection responses that business teams can act on
Prepared with AI assistance by Alactic Editorial. Examples identified as hypothetical are illustrative, not customer results.
A rejected customer update should not leave operations asking whether to fix a field, request access, or resubmit the whole file. An API validation error contract should answer those questions directly: identify the failure category, reference the affected record and field safely, state what was accepted, and name the team responsible for correction.
Agree those meanings before polishing error messages. A readable sentence cannot compensate for an ambiguous processing outcome. If some records were accepted, the response must distinguish them from rejected records. If nothing was accepted, it must say so rather than making the receiving team infer that from a status code.
The practical starting point is a rejection-response matrix shared by the API owner, the integration team, and the business team that supplies the data. The filled hypothetical matrix below shows what that agreement can contain.
Separate the failure reason from the acceptance outcome
Two independent questions belong in every rejection design:
- Why could the request not proceed as submitted? Examples include an invalid field, an unsupported value, or insufficient permission.
- What happened to the submitted work? Nothing was accepted, some records were accepted, or the request was accepted for a later processing stage.
Do not treat partial acceptance as just another field error. It is an overall outcome that can contain several different rejection reasons. A batch might accept valid records while rejecting one record for a missing field and another for insufficient permission.
Also define the boundary of acceptance. Does accepted mean stored as a draft, admitted to a processing queue, or applied to the destination record? Pick a precise meaning for each operation. Acceptance into a queue is not confirmation that the final business action happened.
HTTP status remains useful to software, but it should not carry the whole explanation. Document the status convention alongside the response body. Receiving teams should not have to guess whether a particular status means every record failed or whether individual record outcomes must still be inspected.
Define the minimum useful response
A recommended contract has a small set of stable fields with documented meanings. The names below are illustrative design choices, not an existing product specification.
- Request reference: a reference the receiving team can give the API owner without copying the full payload.
- Overall outcome: an explicit value such as rejected, partially accepted, or accepted, with its processing boundary documented.
- Acceptance scope: whether the operation is all-or-nothing or evaluated record by record.
- Record reference: a caller-supplied reference that can be matched to the source record. Where appropriate, include the original item position as a secondary locator.
- Stable reason code: a machine-readable value that integrations can route without parsing prose.
- Field path and label: the technical location plus a business-readable field name, when disclosure is safe.
- Correction action and owner: the next step and the team authorised to take it.
- Resubmission scope: which rejected records may be corrected and submitted again, subject to the operation's documented duplicate-handling rules.
Keep reason codes stable even when explanatory wording improves. Otherwise a harmless copy edit can break a receiving system that routes exceptions by matching message text.
Client-side checks can make corrections easier, but they do not replace server-side validation. The W3C guidance on input validation also stresses understandable, accessible errors and accommodating varied input formats. For a business-facing correction screen, translate a path such as contacts[2].email into a recognisable record and field label rather than showing only the raw path.
Use this filled hypothetical rejection-response matrix
Fictional worked example: an integration submits customer records to a destination service. Records are evaluated independently. In this hypothetical design, accepted means the customer update has been applied; it does not mean any subsequent communication has been sent. All codes, references, values, counts, and ownership assignments below are hypothetical.
Each entry uses the same matrix columns: category, diagnostic details, record reference, acceptance result, correction action, responsible team, and resubmission rule.
Validation failure: required field missing
- Category and code: validation failure;
REQUIRED_FIELD_MISSING. - Safe diagnostic: field path
customer.external_reference; label Customer reference; message explaining that a non-empty reference is required. Do not echo unrelated customer data. - Record reference: caller item
import-item-A, retained even though the business reference is missing. - Acceptance result: this record rejected; no fields from it applied.
- Correction action: obtain the reference from the source system and add it to the record. Do not invent a placeholder merely to pass validation.
- Responsible team: Customer Data Operations.
- Resubmission rule: submit the corrected rejected record under the documented duplicate-handling contract.
Validation failure: ambiguous date
- Category and code: validation failure;
AMBIGUOUS_DATE. - Safe diagnostic: field path
customer.follow_up_date; label Follow-up date; expected formatYYYY-MM-DD. State that the submitted format cannot be interpreted unambiguously without repeating the value. - Record reference: caller item
import-item-B. - Acceptance result: this record rejected; no partial field update.
- Correction action: confirm the intended date, then correct the export mapping. Do not silently choose a regional interpretation.
- Responsible team: Integration Engineering for mapping; Customer Data Operations confirms the intended date when needed.
- Resubmission rule: resubmit this record after correction; leave accepted records out.
Unsupported value: valid text, unavailable option
- Category and code: unsupported value;
UNSUPPORTED_CUSTOMER_STAGE. - Safe diagnostic: field path
customer.stage; label Customer stage; permitted hypothetical values arenew,active, andinactive, provided that this caller may see that list. - Record reference: caller item
import-item-C. - Acceptance result: this record rejected, not converted to a default stage.
- Correction action: map the source stage to an agreed supported value, or ask the destination configuration owner to assess the mismatch.
- Responsible team: CRM Process Owner decides the business mapping; Integration Engineering implements it.
- Resubmission rule: submit only after the mapping decision is recorded. Repeating unchanged data will not resolve the rejection.
Permission failure: requested operation not authorised
- Category and code: permission failure;
OPERATION_NOT_AUTHORISED. - Safe diagnostic: the caller is not authorised to perform the requested update. Do not disclose the target object's existence, owner, or private attributes.
- Record reference: echo caller item
import-item-D; omit destination-derived details. - Acceptance result: this record rejected; no change applied.
- Correction action: request an access review through the approved internal process. Do not advise changing identifiers or using another person's credentials.
- Responsible team: Access Administration, with the business resource owner approving any access change.
- Resubmission rule: resubmit only after the authorisation issue is resolved.
Partial acceptance: mixed batch outcome
- Category and code: overall outcome
PARTIALLY_ACCEPTED, with separate reasons for rejected records. - Safe diagnostic: in a hypothetical batch of six records, two were applied and four were rejected for the reasons above.
- Record reference: provide an outcome for every caller item, including accepted items
import-item-Eandimport-item-F. - Acceptance result: accepted records remain applied; the rejected records had no changes applied.
- Correction action: split the exception work by reason and owner. Do not resend the original batch as a shortcut.
- Responsible team: Integration Operations reconciles the batch and assigns each rejected record to the matrix owner.
- Resubmission rule: submit corrected rejected records only, using the agreed duplicate-handling rules.
Make partial acceptance independently reconcilable
A response that says some records failed is not enough. The receiver needs to match every submitted item to a definitive result without comparing timestamps or searching the destination manually.
For the hypothetical batch above, the response should contain the six submitted caller references exactly once each, their individual outcomes, and totals that reconcile with those outcomes. An unknown or repeated caller reference should be treated as a reconciliation defect, not quietly ignored.
Decide atomicity at the record level as well as the batch level. If an invalid follow-up date causes the entire customer record to fail, state that no other fields on that record changed. If field-level acceptance is genuinely supported, report accepted and rejected fields explicitly. That finer granularity increases correction complexity and may be unsuitable where fields depend on each other.
An all-or-nothing batch can be easier to reason about when records must remain consistent together. Independent acceptance reduces the amount of valid work held back by unrelated errors. Neither choice is universally better; the response must make the chosen rule observable.
Give useful diagnostics without exposing protected data
More detail is not always more useful. A validation response can identify an email field without repeating the email address. A permission response can identify the submitted item without revealing whether a private destination record exists.
OWASP's object-level authorisation guidance explains why possession of an object identifier does not establish permission to access it. Apply that distinction to diagnostics: a caller's reference is useful for matching work, but it is not a licence to disclose destination attributes.
Agree which details each authorised audience may receive. A business correction view might show the field label, reason, action, and owner. A technical investigation may need a request reference and field path. Neither needs credentials, raw tokens, internal stack traces, or an unnecessary copy of the full request.
Allowed-value lists need the same care. Return them only when they are appropriate for the caller to see and relevant to the current operation. Otherwise direct the owner to an authorised configuration source rather than exposing hidden options.
Assign correction ownership before an exception arrives
The team that receives the rejection is not necessarily the team that can fix it. Integration Operations may coordinate the response while lacking authority to choose a customer stage or grant access.
Name one accountable correction owner for each code. Where another team contributes, describe that handoff specifically. In the matrix, the CRM Process Owner chooses the meaning of a stage mapping; Integration Engineering should not make that business decision merely because it owns the connector.
Keep this ownership mapping in a maintained runbook or configuration rather than relying on free-text team names returned by an external service. The external API can supply the reason code; the receiving organisation maps that code to its current responsible team.
Provide a fallback owner for unknown codes. Its task is to classify the problem and obtain a contract clarification, not to improvise a correction or repeatedly submit unchanged data.
Test the contract with deliberate failures
Run a controlled acceptance exercise before relying on the response in daily work. The exercise should test whether people can act, not merely whether the response parses.
- Submit a record with a missing required value. Ask the data owner to locate the exact field and describe the correction without inspecting application logs.
- Submit a well-formed but unsupported value. Confirm that the response distinguishes a mapping decision from a formatting fix.
- Attempt an update without the required permission. Confirm that no protected object details are exposed and that the access-review owner is clear.
- Submit a mixed batch. Reconcile every item and verify that rejected records produced no unintended changes.
- Correct only rejected items and resubmit under the agreed duplicate-handling rules. Check that previously accepted work is not unintentionally repeated.
If the current response is ambiguous, pause resubmission until the API owner establishes what was applied. Do not convert uncertainty into an assumption that nothing happened. Agree a reliable reconciliation method before restarting the correction flow.
Approve the contract against observable results
The next action is a joint review of the filled matrix by the API owner, Integration Operations, and the named business correction owners. Replace the hypothetical codes and references with the actual contract, then run the controlled cases.
Record three results: whether every submitted item reconciled to an explicit outcome, whether every rejection reached a named correction owner, and whether that owner identified the next action without needing the original developer to interpret the message.
Also record which diagnostics were withheld for safety and whether the remaining information was sufficient. A useful rejection contract balances correction detail with access boundaries. It is ready when the receiving team can distinguish fixable data, unsupported business choices, access decisions, and already accepted work without guessing.
Put the next conversation to work.
Explore Alactic Communications for WhatsApp conversations, campaigns and AI-assisted workflows. Choose the product and plan that fit your team.
Explore Communications