API contracts / App Service v2 / Files

Append a chunk to a resumable upload

OperationappendFileChunk
Call
PATCH /gateway/urvi-app-service/api/v2/files/{fileId}
Group
Files
Features
Add/Edit farmer (IE profile), Land assets, Leased land, Geofencing, Crop Actual (portfolio), ATM model (Anytime Money plot), ATM harvest, Crop Actual harvest, Certification survey, Activity Tracker, VO / SHG / Farmer endorsement, VO / SHG surveys, Device registration and remote actions, Pending sync

Use case. Called by the outbox worker to send file bytes in chunks (e.g. 256 KB on 2G/3G) starting at the server's Upload-Offset. After a dropped connection the worker calls HEAD /files/{fileId} and resumes. When the last chunk lands the server verifies sha256 and marks the file COMPLETE.

Rules.

  • Upload-Offset must equal the current server offset (UPLOAD_OFFSET_MISMATCH, 409).
  • Checksum mismatch on completion -> 422 FILE_CHECKSUM_MISMATCH; restart the upload.

Error codes. UPLOAD_OFFSET_MISMATCH, FILE_CHECKSUM_MISMATCH, FILE_NOT_FOUND

Parameters

NameInTypeRequiredMeaningExample
X-App-VersionheaderstringYesApp version `major.minor.patch+build`. Too old -> 426 `VERSION_TOO_OLD`. · pattern ^\d+\.\d+\.\d+(\+\d+)?$2.0.0+200
X-Device-Idheaderstring (uuid)YesApp-scoped device UUID (not ANDROID_ID).6b1f2c3d-0000-4000-8000-00000000d001
X-Request-Idheaderstring (uuid)NoClient-generated request id for tracing; echoed in responses and problems.0e0c5a1b-0000-4000-8000-0000000000a1
Accept-LanguageheaderstringNoLanguage for messages and labels. · one of en, te, ta; default "en"te
X-TenantheaderstringNoTenant code; must match the token. Urvi: `ap.gov`. · one of ap.govap.gov
fileIdpathstring (uuid)YesFile id from `POST /files`.7a6b5c4d-0000-4000-8000-0000000000e1
Upload-OffsetheaderintegerYesByte offset of this chunk; must equal the server's current offset. · ≥ 0262144

Request

Responses

204 Chunk stored.

400 Malformed request or schema violation.

Schema Problem.

Example 400 body
{
  "type": "https://urvi.example.invalid/problems/validation-failed",
  "title": "Validation failed",
  "status": 400,
  "detail": "One or more fields are invalid.",
  "code": "VALIDATION_FAILED",
  "requestId": "0e0c5a1b-0000-4000-8000-0000000000a1",
  "errors": [
    {
      "field": "/mobile",
      "code": "INVALID_MOBILE",
      "message": "Mobile must be 10 digits starting 6-9."
    }
  ]
}

401 Missing, invalid or expired access token. Refresh once, then ask the user to log in; pending outbox ops stay intact.

Schema Problem.

Example 401 body
{
  "type": "https://urvi.example.invalid/problems/token-expired",
  "title": "Session expired",
  "status": 401,
  "detail": "The access token has expired.",
  "code": "TOKEN_EXPIRED",
  "requestId": "0e0c5a1b-0000-4000-8000-0000000000a1"
}

403 Authenticated but not allowed (role, tenant, device binding or feature switch).

Schema Problem.

Example 403 body
{
  "type": "https://urvi.example.invalid/problems/role-not-allowed",
  "title": "Not allowed",
  "status": 403,
  "detail": "Your role cannot perform this action.",
  "code": "ROLE_NOT_ALLOWED",
  "requestId": "0e0c5a1b-0000-4000-8000-0000000000a1"
}

404 Resource not found or outside the user's work nodes.

Schema Problem.

Example 404 body
{
  "type": "https://urvi.example.invalid/problems/not-found",
  "title": "Not found",
  "status": 404,
  "detail": "No such resource in your work area.",
  "code": "NOT_FOUND",
  "requestId": "0e0c5a1b-0000-4000-8000-0000000000a1"
}

409 Offset mismatch; HEAD and resume.

Schema Problem.

Example 409 body
{
  "type": "https://urvi.example.invalid/problems/upload-offset-mismatch",
  "title": "Offset mismatch",
  "status": 409,
  "detail": "Expected offset 262144.",
  "code": "UPLOAD_OFFSET_MISMATCH",
  "requestId": "0e0c5a1b-0000-4000-8000-0000000000a1",
  "context": {
    "expectedOffset": 262144
  }
}

422 Checksum mismatch.

Schema Problem.

Example 422 body
{
  "type": "https://urvi.example.invalid/problems/file-checksum-mismatch",
  "title": "Checksum mismatch",
  "status": 422,
  "detail": "The uploaded bytes do not match the declared sha256.",
  "code": "FILE_CHECKSUM_MISMATCH",
  "requestId": "0e0c5a1b-0000-4000-8000-0000000000a1"
}

426 App version below the minimum; block the UI with an update prompt. Pending outbox ops are kept.

Schema Problem.

Example 426 body
{
  "type": "https://urvi.example.invalid/problems/version-too-old",
  "title": "Update required",
  "status": 426,
  "detail": "Please update Urvi to continue.",
  "code": "VERSION_TOO_OLD",
  "requestId": "0e0c5a1b-0000-4000-8000-0000000000a1",
  "minAppVersion": "2.0.0"
}

429 Rate limited per device / user. Respect `Retry-After`.

Schema Problem.

Example 429 body
{
  "type": "https://urvi.example.invalid/problems/rate-limited",
  "title": "Too many requests",
  "status": 429,
  "detail": "Slow down and retry later.",
  "code": "RATE_LIMITED",
  "requestId": "0e0c5a1b-0000-4000-8000-0000000000a1",
  "retryAfterSeconds": 30
}

500 Unexpected server error; retry with backoff (writes are idempotent).

Schema Problem.

Example 500 body
{
  "type": "https://urvi.example.invalid/problems/internal-error",
  "title": "Server error",
  "status": 500,
  "detail": "Something went wrong. Please try again.",
  "code": "INTERNAL_ERROR",
  "requestId": "0e0c5a1b-0000-4000-8000-0000000000a1"
}