hackforla
UXD - Blank Map Error States
Overview
We need to create error states for the blank map user flow so users can be properly notified of errors, why they are occurring, and how they can proceed with task completion.
More Details
- This ticket follows up on foundational work completed in #1944. See resources for reference material to prior work on Blank Map Error States
- Error states correspond to specific HTTP errors. HTTP act as a message to tell us what exactly went wrong while the browser (aka the user) attempted to talk to the server (aka the API). The relevant HTTP errors that we should consider for this ticket are listed in the resources below.
Action Items
- [x] API is Down for Maintenance
- [x] Consider adding the following message: "Please check the city's open data portal or the dataset API dev portal for more info"
- link to open data portal page: https://data.lacity.org/City-Infrastructure-Service-Requests/MyLA311-Service-Request-Data-2025/h73f-gn57/about_data
- link to developer portal: https://dev.socrata.com/
- [x] Consider adding the following message: "Please check the city's open data portal or the dataset API dev portal for more info"
- [x] No Results from API
- [x] Consider the component heading title "No matches found"
- [x] Consider Body copy: "We couldn't find any 311 requests matching your search parameters. You can try searching for more request types or over a longer date range."
- [x] Consider exit choices:
- [x] Option 1: No button, just the ability to x out of the pop up.
- [x] Option 2: user clicks "Okay"
- [x] Network/Connectivity error
- [x] Consider the component heading title "Connection failed" or "check connection"
- [x] Include text:
Please check your internet connection and try again - [x] Include buttons for manual retries:
Try againorCancel
- [x] Data Not Published
- [x] Include text: "The dataset for [YEAR] is not yet available. Please check https://myla311.lacity.gov/s/ for more information"
- [x] Document user interaction in Figma
- [x] Update the Hand Off section of this ticket with the final iteration of this design
Design Iterations
Please move ticket between In Progress and In Review to assist PM team
Hand-off and iteration are subject to future updates if required.
Iteration 1
Link to notes: Comment
Connectivity dialog UI iteration
No Published Data for Calendar
No Result (Matches) Found Dialog
Auto-reloading Dialog
Filter Modal Inline Error - Made Changes for Error Messages
Loader Changes
Error Page Light & Dark Theme
Hand Off Materials
Figma Section Name: UXD - Blank Map Error States #2024
Before Screenshot
N/A: We were not accounting for API errors or connectivity errors
After Screenshot (Finalized)
As we were not accounting for API errors or connectivity errors, here's the initial user flow cases and UI designs:
Widgets Overview
Error Cases
Error 500 Case for Internal Server Error with Light Theme
- This error occurs anywhere: When users entering the site, processing data, and exploring the site, and so on.
Map Case
Site Entering Case
Error 404 Case for Page/Data Not Found with Light Theme
- And for other cases of error 404, once the API server issue fixed and page loaded successfully, show the latest page users viewed.
Error 408 Case for Timeout with Light Theme
- User could not complete the request (the data processing)
Error Case 503 for Service Unavailable
- Server API is unavailable, likely down for maintenance. User must wait until maintenance is completed This error is usually happened during maintenance so there probably be announcement before, so there's also possibility that this api error occurs once users enter the site.
Here I put two cases for now:
Connectivity Case
- similar and can be included in error 408
No Result (matches) Found Case
Filter Modal Inline Error Case
Data Not Published Case for Calendar
Designer Resources
Handoff for #1944
- Ticket: #1944
- Figma: Hand-Off - Issue #1944
Iteration Dropdown Copy/Paste
<details><summary>Iteration X</summary>
<p>
Link to notes: `REPLACE WITH COMMENT URL`
`REPLACE WITH SCREENSHOT UPLOAD`
</p>
</details>
Instructions for Engineering Hand Off
To Start Engineering Hand Off...
- Ensure all Hand Off Materials are filled in
- Add the "ready for dev lead" label
- Leave a comment saying "This ticket is ready for engineering hand off."
HTTP Code Reference
Please use the following table to learn more about status codes 200, 408, 500, and 503
📊 HTTP Code lookup table
| HTTP Status Code | Explanation | Source | Special Notes |
|---|---|---|---|
| 200 OK | API successfully provided data to the user | MDN Reference | If the user's filter criteria is overly constrained (no data meets the search criteria), the API will still return an empty list with status 200. |
| 408 Request Timeout | User could not complete a request to the API | MDN Reference | — |
| 500 Internal Server Error | Server API is broken; user must wait until error is fixed by the API owner | MDN Reference | — |
| 503 Service Unavailable | Server API is unavailable, likely down for maintenance. User must wait until maintenance is completed | MDN Reference | — |
@Joy-Truex I've updated the labels and I think we're good to move forward with this ticket. Please add ready for prioritization if it has everything the designer needs.
Edits: Overview
I replaced...> We need to create error states for the blank map user flow so users can be properly notified of errors, why they are occurring, and how they can proceed with task completion.
With...
We need to create error states for the blank map user flow so users can be properly notified. We want to clarify the reason for the error and how they can resolve it so that users can proceed with using the map.
Edits: More Info
Added the following section to clarify ticket relationship.
This ticket follows up on foundational work completed in #1944. See resources for reference material to prior work on Blank Map Error States
Edits: Action Items
I modified the group names...
- Network/API Error → API Error
- Connectivity Error → Network/Connectivity Error
My reasoning is that Network/Connectivity is your problem as a user, and API Error is our problem, as a website.
The ticket might take a bit longer to complete — around a few weeks. as I’m still recovering a bit. I will keep you updated
@Joy-Truex I'm designing API errors. And I guess I better not mention wether the error was an API error or an API server? I guess the errors are for all to view including devs and users
@kiranofans I left a few comments! Feel free to review this doc as well.
Hope it helps, let me know if you have more questions!
@kiranofans I left a few comments! Feel free to review this doc as well.
Hope it helps, let me know if you have more questions!
right sorry I forgot about this document. Thanks for mentioning
Q: @ryanfchase for 408 error, how long will the page attempt to reload? and is that something that is automatically determined, determined by the dev team, or determined by design? thanks!
A: for 408 error, we should auto-retry once, then prompt them to try again or cancel (408 is definitive answer so doesn't suggest continuing to wait)
Another case (which isn't technically 408 error) is the site "hangs" ("in limbo") and is not effectively loading; in this case you prompt them to try again or cancel. For this instance, we should apply the connectivity error
Q: @ryanfchase for 408 error, how long will the page attempt to reload? and is that something that is automatically determined, determined by the dev team, or determined by design? thanks!
A: for 408 error, we should auto-retry once, then prompt them to try again or cancel (408 is definitive answer so doesn't suggest continuing to wait)
Another case (which isn't technically 408 error) is the site "hangs" ("in limbo") and is not effectively loading; in this case you prompt them to try again or cancel. For this instance, we should apply the connectivity error
Still the question regarding timeout, how long will it be for it? 5 seconds?
@kiranofans any research I've done says ideally no longer than 3 but certainly no longer than 5 seconds, but product team feel free to weigh in
@kiranofans @Joy-Truex let's go with 5 seconds (even though I know the API may take longer in many instances) -- and we will collect data over time to see if this is too short of a time window. We can always bump the number up in the future (or consider other design decisions)
@Joy-Truex I’ve almost completed the ticket. It would be great to have a final team review. I guess I’ll also add the current design iterations and use cases to the GitHub ticket.