Digi-Key API Products have shared principles, they include:
OAuth
Digi-Key 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.