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:
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 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.
| Scope | Description | API endpoints |
| /person/update | Biographical data—the left column of the ORCID record user interface. | /address /external-identifier /keywords /other-names /researcher-urls |
| /activities/update | Research 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.
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.