Shared Concepts

DigiKey API Products have shared principles, they include:

OAuth

DigiKey APIs implement the OAuth 2.0 authorization framework. The Oauth2 framework is the industry standard way to give third-party applications secure delegated access to protected resources. Every request made to a DK API will require an access token.
The expectation is you will be familiar with OAuth 2.0 and its utilization of the authorization code grant flow, authorization endpoints, token endpoints, redirection endpoints, bearer tokens, and refresh tokens. The authorization code grant flow is the only permitted way of accessing DK APIs.

TLS

To protect both parties’ resources, all HTTP traffic is secured using the TLSv1.2 encryption protocol. Client applications will be developed to use TLSv1.2. When accessing DK resources, please validate the endpoint and that it uses TLS.

Access Control

To protect both parties’ resources it is important to keep the client application’s Client ID and Client Secret private and secured. Third-party applications are assigned a Client ID and Client Secret. Both the Client ID and Client Secret are unique to the third-party application. They should be secured and should never be made public.

Rate Limits

DK API products have rate quotas. Rate limits are applied at product level. An application is rate limited by both the number of requests per minute and number of requests per day at the product level.

The rate limits below are for standard products.

Standard Product	Rate limit per minute	Rate limit per day
Barcode	120 per minute	1000 per day
Create BOM	10 per minute	-
Order Support	120 per minute	1000 per day
Ordering	10 per minute	-
Product Information	120 per minute	1000 per day
Quoting	10 per minute	-

Every API response is accompanied by the following set of response headers to identify the status of your client application's consumption.

Header	Description
`X-RateLimit-Limit`	The maximum number of requests that the consumer is permitted to make per day.
`X-RateLimit-Remaining`	The number of requests remaining in the current rate limit window.

Once an application hits a rate limit window, the client application will receive a status code of:

429 Too Many Requests

If the burst limit window is exceeded, the response headers will show:

Header	Description
Retry-After	The seconds until you can retry the request
X-BurstLimit-Limit	The maximum number of requests allowed for the API, number per minute
X-BurstLimit-Remaining	The number of requests remaining in the current rate limit window.
X-BurstLimit-Reset	The seconds until the burst limit window resets
X-BurstLimit-ResetTime	The time when the burst limit window resets, GMT

and the JSON response message will be like:

{
    "ErrorResponseVersion": "3.0.0.0",
    "StatusCode": 429,
    "ErrorMessage": "BurstLimit exceeded",
    "ErrorDetails": "Please try again after the number of seconds in the Retry-After header",
    "RequestId": "fa3e4d88-bfc4-4565-c6d5-a567633c091b",
    "ValidationErrors": []
}

If the daily limit window is exceeded the response headers will show:

Header	Description
Retry-After	The seconds until you can retry the request
X-RateLimit-Limit	The maximum number of requests allowed for the API
X-RateLimit-Remaining	The number of requests remaining in the current rate limit window.
X-RateLimit-Reset	The seconds until the exceeded rate limit window resets
X-RateLimit-ResetTime	The time when the rate limit window resets, GMT

and the JSON response message will be like:

{
    "ErrorResponseVersion": "3.0.0.0",
    "StatusCode": 429,
    "ErrorMessage": "Daily Ratelimit exceeded",
    "ErrorDetails": "Please try again after the number of seconds in the Retry-After header",
    "RequestId": "f4a0c1ab-8b47-4a72-e010-8ebe5d78f96c",
    "ValidationErrors": []
}

Status Codes

Each API documents the status codes it will send. The response codes returned follow RFC 22616 specifications. Generally the status codes returned are:

HTTP Status Code	Description
`200 OK`	Successful.
`400 Bad Request`	Bad input parameter. Error message should indicate which one and why. Somehow your client request is malformed/invalid. Also possible, but less likely, the requested part has not been found.
`401 Unauthorized`	The client passed in the invalid access token. Client should refresh the token and then try again. Or you have not subscribed the client application to a DK API product.
`404 Not Found`	Resource not found.
`405 Method Not Allowed`	The resource doesn't support the specified HTTP verb. You are making a request in a format that is not expected. Example is making a GET request when the data needs to be presented as POST.
`429 Too Many Requests`	Too many request for rate limiting. Too many requests in a given period of time (>120 per minute), or more than allowed during the current rate limit window.
`500 Internal Server Error`	Servers are not working as expected. The request is probably valid but needs to be requested again later.
`503 Service Unavailable`	Service Unavailable.

Support

For technical concerns about accessing or using DK APIs, visit the support page.

Learn More