Searches fail on the old endpoint
How you'll know: Calls to /rest/api/3/search or /rest/api/2/search return errors.
Fix: Atlassian has removed those endpoints from Jira Cloud. Move to /rest/api/3/search/jql. It pages with nextPageToken instead of startAt, so loops that counted by offset need rewriting. Ask for the fields you need explicitly. Our JQL page covers the query side.
A 401 out of nowhere
How you'll know: Every call starts failing authentication on the same morning, with no code change.
Fix: The token expired. Tokens now carry an expiry date you choose, from one day to a year, and since December 2024 new ones default to a year. Make a new one, and note the expiry date somewhere your team will see it.
A new scoped token gets rejected
How you'll know: You made an API token with scopes, and your site URL refuses it.
Fix: Scoped tokens go through Atlassian's gateway, https://api.atlassian.com/ex/jira/{cloudId}/rest/api/3/..., not your-site.atlassian.net. Swap the base URL.
The description field throws an error
How you'll know: Creating or editing an issue on v3 fails with a message that the value must be an Atlassian Document.
Fix: v3 wants descriptions and comments as Atlassian Document Format JSON, not a plain string. Build the small ADF structure (a doc containing a paragraph containing text), or send plain text to the v2 endpoint instead.
User fields are empty or rejected
How you'll know: Old code sets the assignee or reporter by username, and nothing happens.
Fix: Jira Cloud identifies people by accountId. Look it up with /rest/api/3/user/search?query= and an email or name, and cache the result.
A transition stops working after a workflow edit
How you'll know: Moving issues to Done fails, or moves them somewhere unexpected.
Fix: Transition IDs belong to a workflow, and an admin changed it. Fetch the available transitions for each issue and pick by name instead of hardcoding the number.
Bulk jobs get 429s
How you'll know: A migration or nightly sync fails partway through with 429 Too Many Requests.
Fix: Read the Retry-After header, wait that long, and spread big jobs out instead of firing requests in parallel.