# Unified API Response Contract — Flutter & Dashboard

**Applies to:** Outlet API `/api/v1` responses after the Capitalix-style contract update is released. **Status:** implemented on a GitLab feature branch; not yet verified in staging. Do not treat examples as live captures.

## Successful JSON requests

```json
{"message":"Retrieved successfully.","data":{"id":125,"reference":"ABC-1234"}}
```

- HTTP status remains 200, 201, etc. No JSON `status`, `errors`, or `code` keys on success.
- `message` is a translated display string; do not use it for branching.
- `data` is an object. Lists use `data.items`, empty data is `{}`, scalar data is `data.value`.
- If the endpoint returns a named collection, retain the documented collection name. Nested fields are endpoint-specific.
- `204`/`205`: no JSON body; don't attempt JSON decoding. File downloads and streams are not wrapped.

## Error JSON

```json
{"message":"The email field is required.","errors":{"email":["The email field is required."]},"code":"VALIDATION_FAILED","correlation_id":"550e8400-e29b-41d4-a716-446655440000","details":{}}
```

- `errors`: field-to-string-array map, `{}` when there are no field errors.
- `code`: stable machine-readable uppercase string; handle unknown future codes gracefully.
- `details`: optional error-specific metadata represented as an object; do not assume any particular field exists.
- `correlation_id`: request tracing ID; include it in support reports. It is **not** an order, payment, or session ID.
- Never display `details` blindly; show `message` or field messages. Never expose internal diagnostics.

### HTTP handling

| HTTP | Typical code | Client action |
|---|---|---|
| 400 | `BAD_REQUEST` | Correct request; show message |
| 401 | `UNAUTHENTICATED` | Clear/refresh credentials according to auth flow |
| 403 | `PERMISSION_DENIED` or module code | Show access restriction; don't automatically log out |
| 404 | `NOT_FOUND` or module code | Show missing/unavailable resource |
| 405 | `METHOD_NOT_ALLOWED` / `HTTP_ERROR` | Integration error; report to team |
| 409 | `CONFLICT` or module code | Refresh record or resolve conflict |
| 422 | `VALIDATION_FAILED` or module code | Bind `errors[field]` to inputs; show message |
| 429 | `RATE_LIMITED` | Respect `Retry-After` when supplied |
| 500+ | `INTERNAL_ERROR` or service code | Generic failure, retry/report correlation ID |

These are general client behaviors; a module-specific code may override the UX. The HTTP status and `code` are separate values.

## Headers and locale

- Send `Accept: application/json`, `Accept-Language: ar` or `en`, and the authentication header required by the endpoint.
- You may send `X-Correlation-Id`; otherwise the server generates one. Read it from response header `X-Correlation-Id`, or from error JSON `correlation_id`.
- The legacy `X-Request-ID` response header is retained during migration, but new clients should prefer `X-Correlation-Id`.
- Localized messages may change; never compare translated message text.

## Pagination

```json
{"message":"Retrieved successfully.","data":{"items":[{"id":1}],"meta":{"current_page":1,"last_page":2,"total":30,"per_page":20,"max_per_page":100}}}
```

For pages, consume `data.meta.current_page`, `last_page`, `total`, `per_page`, `max_per_page` where provided. Don't assume all list endpoints paginate or all use the key `items`.

## Migration from legacy responses

| Legacy | New |
|---|---|
| `error.code` | top-level `code` |
| `error.message` | top-level `message` |
| `error.details` | top-level `details` |
| `error.request_id` | top-level `correlation_id` |
| `data` as a bare array | `data.items` |
| `data` object | `data` object (plus top-level `message`) |

Update **one central API client/parser** in Flutter and Dashboard rather than adding per-screen workarounds. During rollout, the backend and both clients must use the same contract version. `204`, downloads, network errors and malformed JSON require separate handling.

## Integration checklist

- Success: 200 object, 200 list, 201 creation, 204 deletion, paginated list.
- Errors: 401, 403, 404, 409, 422 field errors, 429 retry, 500 safe message.
- Headers: correlation ID, Arabic/English content, authenticated/anonymous requests.
- Edge cases: null/empty data, optional fields, binary files, expired tokens, network timeout, offline.

**Verification:** Source-based target contract; no staging HTTP evidence yet. Endpoint-level examples elsewhere in this handoff are reference payloads, not guaranteed runtime captures.
