Referrals API Response Codes

2024-11-12

Applies to: Partner Center | Partner Center Referrals

Appropriate roles: Referrals admin | Referrals user

The Partner Center Referrals REST APIs return a JSON object that contains a status code. This code that indicates whether your request was successful or why it failed.

Success responses

A 2xx status code indicates that the client's request was successfully received, understood, and accepted. The following 2xx status codes indicate a success response:

200: Success confirmed
201: Resource created
202: Accepted
204: No content to return

Error responses

Any response with a 4xx or 5xx status code includes an error message with details about the error conditions for that code.

The following table lists and describes the HTTP status codes that can be returned for error scenarios.

Status code	Status message	Description
400	Bad Request	Can't process the request because it's malformed or incorrect.
401	Unauthorized	Required authentication information is either missing or not valid for the resource.
403	Forbidden	Access is denied to the requested resource. The user might not have enough permission.
404	Not Found	The requested resource doesn't exist.
405	Method Not Allowed	The HTTP method in the request isn't allowed on the resource.
406	Not Acceptable	This service doesn't support the format requested in the Accept header.
409	Conflict	The current state conflicts with what the request expects. For example, the specified parent folder might not exist.
410	Gone	The requested resource is no longer available at the server.
411	Length Required	A Content-Length header is required on the request.
412	Precondition Failed	A precondition provided in the request (such as an if-match header) doesn't match the resource's current state.
413	Request Entity Too Large	The request size exceeds the maximum limit.
415	Unsupported Media Type	The content type of the request is a format which service doesn't support.
416	Requested Range Not Satisfiable	The specified byte range is invalid or unavailable.
422	Unprocessable Entity	Can't process the request because it's semantically incorrect.
423	Locked	The resource that is being accessed is locked.
429	Too Many Requests	Client application is throttled and shouldn't attempt to repeat the request for some time.
500	Internal Server Error	There was an internal server error while processing the request.
501	Not Implemented	The requested feature isn't implemented.
503	Service Unavailable	The service is temporarily unavailable for maintenance or is overloaded. You may repeat the request after a delay, the length of which may be specified in a Retry-After header.
504	Gateway Timeout	The server, while acting as a proxy, didn't receive a timely response from the upstream server it needed to access in attempting to complete the request. May occur together with 503.
507	Insufficient Storage	Reached the maximum storage quota.
509	Bandwidth Limit Exceeded	Client application throttled for exceeding the maximum bandwidth cap. Your app can retry the request again after some time.

Error resource type

The error response is a single JSON object that contains a single property named error. This object includes all the details of the error. You can use the information returned here instead of or in addition to the HTTP status code.

The following table and code samples describe the schema of an error response.

Name	Type	Description
code	string	Always returned. Indicates the kind of error that occurred. Non-null.
message	string	Always returned. Describes the error in detail, and provides more debugging information. Non-null nonempty. Maximum length is 1,024 characters.
innerError	object	Optional. Another error object with more specific information regarding the error occurred.
innerError.code	numeric string	Always returned, if innerError is non-null. Provides more specific error code information under the top error code value.
innerError.message	string	Always returned, if innerError is non-null. Provides more specific error message under the top error message string.
innerError.details	array object	Optional. Contains more details about the error. Primarily useful in input validation errors.
target	string	Optional. The target where the error originated.

Sample error response

{
  "error": {
    "code": "unauthenticated",
    "message": "The caller is not authenticated.",
    "innerError": {
      "code": "99902",
      "message": "Request not authenticated",
      "details": null
    }
  }
}

Another sample with innerError.details object populated:

{
  "error": {
    "code": "invalidRequest",
    "message": "The request is malformed or incorrect.",
    "innerError": {
      "code": "99901",
      "message": "InvalidInput",
      "details": [
        {
          "InvalidReferralForCoSellConversion": [
            "If PartnerLed referral has no solution it cannot be converted to co-sell referral"
          ]
        }
      ]
    }
  }
}

Code property

The code property contains one of the following possible values. Your apps should be prepared to handle any one of these errors.

Code	Http status code	Description
invalidRequest	400	The request is malformed or incorrect.
unauthenticated	401	The caller isn't authenticated.
accessDenied	403	The caller doesn't have permission to perform the action.
itemNotFound	404	The resource couldn't be found.
resourceModified	409	The resource being updated changed since the caller last read it, usually an eTag mismatch.
preconditionFailed	412	A precondition provided in the request (such as an if-match header) doesn't match the resource's current state.
generalException	500	An unspecified error occurred.
serviceNotAvailable	503	The service isn't available. Try the request again after a delay. There may be a Retry-After header.

Message property

The message property at the root contains an error message intended for the developer to read. Error messages aren't localized and shouldn't be displayed directly to the user. Your code shouldn't check against message values only because they can change at any time, and they often contain dynamic information specific to the failed request. You should code against error codes returned in code properties and then for more details combine it with message text.

InnerError object

The innererror object might recursively contain more innererror objects with more specific error codes. Client application, when handling an error, should loop through all the error codes available and use the most detailed one that they understand.

There are some more errors that your app might encounter within the nested innererror objects. Apps aren't required to handle these errors, but can do it if they choose. The service might add new error codes or stop returning old ones at any time, so it's important that all apps be able to handle the [basic error codes].

Error codes

The following are error codes returned by the APIs:

HTTP Status	HTTP Error Code	Error code	Description
BadRequest	400	99901	Invalid input
Unauthorized	401	99902	Unauthorized access
BadRequest	400	99903	Missing input
NotFound	404	99904	Resource not found
InternalServerError	500	99905	Error not specified
TooManyRequests	429	99906	Too many requests
InternalServerError	500	99907	Transient internal error
BadRequest	400	99908	Property is nonupdatable
BadRequest	400	99909	Property is non-nullable
PreconditionFailed	412	99910	Etag value doesn't match
BadRequest	400	99911	Invalid referral status to invite
BadRequest	400	99912	Solution with type 'name' is required
Forbidden	403	99913	Organization not allowlisted to create resource
Forbidden	403	99914	Organization not allowlisted to participate in co-sell engagements
InternalServerError	500	99915	Internal request execution failure
Conflict	409	99917	Resource already modified via another request
PreConditionFailed	412	99918	A precondition provided in the request (such as an if-match header) doesn't match the resource's current state.
BadRequest	400	99919	Invalid referral qualification to update
InternalServerError	500	99999	General exception while processing request