• Skip to primary navigation
  • Skip to main content
  • Skip to primary sidebar

Connecting Researchers and Research

Sign in/Register
  • About
        • Our Mission
          • 2025 Vision
          • ORCID Trust
          • Annual Reports
        • Team
          • ORCID Board
          • ORCID Team
          • Work with Us!
        • Services
          • Member Portal
          • Annual data files
          • Member API
          • Public API
          • ORCID Registry
        • Governance
          • Bylaws
          • Board Elections
        • Policies
          • Privacy Policy
          • Dispute Procedures
          • Public Client Terms of Service
          • Open Source Project License
          • Public Data File Use Policy
          • Terms of Use
          • Brand Guidelines
  • For Researchers
        • Benefits for Researchers
        • Researcher FAQ
        • Video Tutorials
        • Sign in / Register
        • Get Help
  • Membership
        • Membership Benefits
          • Benefits for Funders
          • Benefits for Publishers
          • Benefits for Research Organizations
          • Benefits for Research Resources
        • Get Membership
        • Member List
        • ORCID Map
        • Membership Comparison
          • Basic Membership
          • Premium Membership
          • ORCID Consortia
        • ORCID Consortia
          • Consortia Agreement
          • Consortia Onboarding Checklist
          • Roles and Responsibilities of ORCID Consortia
  • Documentation
        • Features
          • Member Portal
          • Member API
          • Public API
          • ORCID Registry
          • Annual Data Files
        • Workflows
          • Journal Articles
          • Employment
          • Peer Review
          • Funder and Grants
          • View More
        • Integration Guide
          • Getting Started with Your Integration
          • Sandbox Testing Server
          • Registering a Member API Client
          • Integration and API FAQ
          • View More
        • API Tutorials
          • Get an Authenticated ORCID iD
          • Read Data on a Record
          • Add and Update Data on an ORCID record
          • Hands On with the ORCID API
          • View More
  • Resources
        • ORCID Community
        • Community Programs
          • Certified Service Providers
          • ORCID API Users Group
          • Historical Task Forces, Working Groups, and Steering Groups
        • Get Involved
          • Community Groups
          • Developers
          • Give Feedback
          • ORCID API Users Group
        • Member Resources
          • ORCID Enabled Systems
          • Publishers Open Letter
          • Funders Open Letter
          • Standard Member Agreement
          • Outreach Resources
          • Register a Sandbox API Client
          • Register a Production API Client
  • News & Events
        • News
          • ORCID News
          • Member News
          • Consortia News
          • Integration News
          • Blog
          • Release Notes
        • Events
          • Events Calendar
          • Webinars
You are here: Home / Documentation / Integration Guide / Troubleshooting

Troubleshooting

Contents
1. API Errors
1.1. What do ORCID API error codes mean?
1.2. XML/JSON formatting errors
1.3. How should data be formatted for the API?
1.4. Scope errors
1.5. What is an OAuth scope, and which scopes does ORCID support?
1.6. 3-legged (authorization code) scopes
1.7. 2-legged (client credential) scopes
1.8. Which sections can I add to or update on an ORCID record?
2. Registry error messages
2.1. Bad redirect URI
2.2. Bad link to OAuth authorization form
2.3. Non-descriptive message
3. Check if ORCID is working!
4. Getting help

We do our best to provide descriptive error messages in our Registry and API. Here are some tips to help you out with any errors you may encounter.

API Errors

Our API error codes include descriptive messages that should be easily understandable.

What do ORCID API error codes mean?

A list of common API error codes, their possible meanings and tips on how to troubleshoot them is available within our technical documentation.

If you are not able to resolve the issue that you are experiencing the please do let us know.

XML/JSON formatting errors

If you’re having trouble with formatting the data you are trying to add or update on an ORCID record, we recommend consulting examples by:

  • Sending a call to read the record or individual item to receive example XML/JSON, or, if you’re updating a record, the full XML/JSON for the item that you are updating, and use this as your starting point
  • Consulting our sample XML and JSON files in our GitHub repository — we have both clean XML/JSON for posting and full XML/JSON for read examples

How should data be formatted for the API?

Before you can add an item to the ORCID record you will need to format your data into the ORCID schema. Format your data in the ORCID message schema in XML or JSON.

Our GitHub repository contains resources that will help with formatting when creating new items on the ORCID record, and when reading existing items on the ORCID record:

  • Example XML files
  • The XSD for all sections of the ORCID record

Note that different versions of the API have different message formats. Version 2.0 and 2.1 schemas and examples are also available.

More examples can be easily found by reading the metadata of a well populated record.

Scope errors

If you are receiving errors relating to scopes then we would recommend that you:

  • Check you are not using member scopes with a public API client.
  • If you are adding, updating or reading limited visibility data that that you have the correct scopes to perform the action.
  • Check you are not requesting 2-legged scopes using 3-legged OAuth and vis-versa.

What is an OAuth scope, and which scopes does ORCID support?

When requesting permission to interact with an ORCID user’s record, you specify one or more ‘scopes’. Each scope allows you to do certain things, such as read the record, or update a particular section.

3-legged (authorization code) scopes

3 legged refers to the three actors involved in obtaining permission from a user; ORCID, your system and the user themselves.

/authenticate

This scope is used to collect the ORCID iD and read public information on the record only. All other 3-legged scopes include the authenticate permission, so this scope can be omitted if asking for any other access. This scope is available on the Member or Public API.

/read-limited (Member API only)

This scope is used to get access to read public and limited visibility items on an ORCID record. This scope is only available on the Member API.

/activities/update (Member API only)

This scope is used to write, update and delete items in the affiliation, funding, works and research resources and peer-review sections of an ORCID record. This scope is only available on the Member API.

/person/update (Member API only)

This scope is used to write, update and delete items in the other-names, keywords, countries, researcher-urls, websites, and personal external identifiers sections of the record. This scope is only available on the Member API.

openid

This scope is used by OpenID integrators when an id_token is required. When the openid scope is included, the Registry will return an id_token inside the token response and grant the client permission to access the user info endpoint for that user. This scope is available on the public and member API.

Please note that the ‘openid’ scope does not start with a ‘/’ like the other ORCID API scopes. This is because the ‘openid’ scope is not defined by ORCID, but instead defined by the OpenID Connect specification. Please see our OpenID documentation for more information.

Multiple scopes

Multiple scopes can be requested in a single interaction by listing the scopes in the authenticate URL with an encoded space between each, such as scope=/read-limited%20/activities/update%20/person/update

Complete access

If you want full access to read and edit a record include three scopes in your authenticate URL: /read-limited, /activities/update and /person/update. In the URL they would appear as scope=/read-limited%20/activities/update%20/person/update

2-legged (client credential) scopes

For some activities you do not have to ask the user for permission. Two legged OAuth scopes are requested directly from the ORCID API and do not require the researcher to grant permission. Tokens with these scopes are valid for 20 years and can be reused

/read-public

This scope is used to read public information on a single ORCID iD or search for ORCID records. This scope is available on the Member or Public API.

/webhook

This scope allows a client application to register a webhook on an ORCID record, in order to receive notifications when a record is updated. This scope is available to premium ORCID members only. If you are not a premium member, but wish to test this function in the Developer’s Sandbox, please contact ORCID Community.

  • In the past ORCID supported other scopes, that have now been phased out.
  • You can find out which scopes are required to add or update a particular sections here.

Which sections can I add to or update on an ORCID record?

There are two different update scopes – one for biographical details, the other for activities.

ScopeDescriptionAPI endpoints
/person/updateBiographical data—the left column of the ORCID record user interface./address
/external-identifier
/keywords
/other-names
/researcher-urls
/activities/updateResearch activity data—the right column of the ORCID record user interface./distinction
/distinctions
/education
/educations
/employment
/employments
/funding
/fundings
/invited-position
/invited-positions
/membership
/memberships
/peer-review
/peer-reviews
/qualification
/qualifications
/research-resource
/research-resources
/service
/services
/work
/works

Registry error messages

Generally your users will only encounter a few API-related errors when authorizing a connection with your application:

Bad redirect URI

Redirect URI doesn't match your registered redirect URIs.

This error message is an indication that your authorization link specifies a redirect URI that you have not registered in your API client credentials. If you are using the public API, you can fix this yourself in your Developer Tools. If you are using the Member API, you will need to request the ORCID Engagement team to update your credentials.

Bad link to OAuth authorization form

The page requested cannot be found. If you have this page bookmarked, please delete it. If you have followed a link, please report it.

This error tends to occur when the OAuth authorization link is improperly formed, e.g. https://orcid.org/signin/oauth/authorize?[….] instead of https://orcid.org/oauth/authorize?[…]. To resolve, simply correct the link.

Non-descriptive message

There has been a problem with the server. If this problem persists, please contact support.

This error most often occurs when no scope is specified. You must include a scope on the OAuth authorization link; the minimum scope is /authenticate.

Check if ORCID is working!

It’s very, very rare, but if you think the error is a problem with the ORCID Servers you can check at https://status.orcid.org/

Note that the ORCID Sandbox does not have a service-level agreement and may be down for 20 minute time periods when we are releasing code updates.

Getting help

We’re always happy to help! ORCID member organizations can get support from ORCID directly.

All integrators are also encouraged to join the ORCID API Users Group, where you can communicate with other integrators and API users, as well as the ORCID team.

Primary Sidebar

Documentation

Documentation MenuDocumentation Menu
  • Features
    • Public API
      • Sign in option to your system
      • Collecting authenticated iDs
      • Reading ORCID records
      • Searching the registry
    • Member API
      • Access trusted data
      • Writing data to ORCID records
      • Syncing ORCID with your system
    • Member Portal
    • ORCID Registry
    • Annual Data Files
  • Workflows
    • Journal Articles
    • Books
    • Preprint Servers
    • Peer Review
    • Education
    • Employment
    • Invited Positions and Distinction
    • Membership and Service
    • Research Resources
    • Funder and Grants
    • Repository Systems
    • eTheses and Dissertation
    • Institutional Connect
    • Search and Link Wizards
    • Sharing User Permissions
    • Connecting with Co-Authors
  • Integration Guide
    • Getting Started with Your Integration
    • Sandbox Testing Server
    • Registering a Public API Client
    • Registering a Member API Client
    • ORCID and Persistent Identifiers
    • Working with Organization Identifiers
    • Sign into ORCID with Institutional Credentials
    • Sign In Using ORCID Credentials
    • Syncronizing with ORCID
    • Working with Bulk Data
    • ORCID Record Schema
    • Troubleshooting
    • User experience display guidelines
    • Customizing the OAuth Experience
    • Vendor Systems
    • Communicating with Users
    • Integration and API FAQ
  • API Tutorials
    • Getting an Authenticated ORCID iD
    • Reading Data on a Record
    • Adding and Updating Data
    • Searching the ORCID Registry
    • Registering a Notification Webhook
    • Hands on with the ORCID API

Github Documentation

Documentation MenuDocumentation Menu
  • API Tech Docs
  • Tech Tutorials
  • Content Negotiation
  • Open ID Connect
  • V3.0 API Schemas
ORCID logo

CC0 The text of this website is published under a CC0 license Images and marks are subject to copyright and trademark protection.

  • About ORCID
  • Privacy Policy
  • Terms of Use
  • Accessibility Statement
  • Contact us
  • Dispute procedures
  • Brand Guidelines
ORCID uses cookies to improve your experience and to help us understand how you use our websites. Learn more about how we use cookies. Dismiss