Partial success handling in Rest API

Introduction

Partial success handling helps your app tell which parts of a request worked and which parts did not. This way, users know exactly what happened without guessing.

When uploading multiple files and some succeed but others fail.

When updating several records and only some updates apply.

When sending batch requests where some actions complete and others don't.

When processing a list of tasks and some finish while others error.

Syntax

Rest API

HTTP/1.1 207 Multi-Status
Content-Type: application/json

{
  "results": [
    {"id": 1, "status": "success"},
    {"id": 2, "status": "error", "message": "Invalid data"}
  ]
}

The HTTP status code 207 Multi-Status is often used to show partial success.

The response body usually contains details about each item's result.

Examples

This example shows two files: one uploaded successfully, the other failed with an error message.

Rest API

HTTP/1.1 207 Multi-Status
Content-Type: application/json

{
  "results": [
    {"file": "image1.png", "status": "uploaded"},
    {"file": "image2.png", "status": "failed", "error": "File too large"}
  ]
}

Here, two tasks are processed: one finished, the other failed due to timeout.

Rest API

HTTP/1.1 207 Multi-Status
Content-Type: application/json

{
  "tasks": [
    {"taskId": 101, "status": "completed"},
    {"taskId": 102, "status": "failed", "reason": "Timeout"}
  ]
}

Sample Program

This simple Flask app accepts a list of file names. It marks files with names shorter than 10 characters as uploaded, others as failed. It returns a 207 status with details.

Rest API

from flask import Flask, jsonify, request

app = Flask(__name__)

@app.route('/upload', methods=['POST'])
def upload_files():
    files = request.json.get('files', [])
    results = []
    for f in files:
        if len(f) < 10:
            results.append({'file': f, 'status': 'uploaded'})
        else:
            results.append({'file': f, 'status': 'failed', 'error': 'File name too long'})
    return jsonify({'results': results}), 207

if __name__ == '__main__':
    app.run(debug=True)

Important Notes

Use HTTP status 207 to clearly indicate partial success.

Always include detailed info in the response body so clients know what succeeded or failed.

Partial success helps avoid confusion and improves user experience.

Summary

Partial success handling tells which parts of a request worked and which did not.

Use HTTP 207 Multi-Status with detailed JSON results.

This approach helps users understand exactly what happened.