Learn About API Errors

Viktorija
Viktorija
  • Updated

API errors can occur in response to your API requests, and this article provides information on error handling and response structure. It includes a list of error status codes along with their descriptions, as well as key fields in error responses, such as reason, message, and params. Understanding these elements helps you efficiently troubleshoot issues.

Error Handling

Standardized error responses help users understand what went wrong. The API will attempt to return appropriate HTTP status codes along with structured error responses for any issues. However, there may be instances where unhandled errors occur, which may not follow the defined error formatting. In such cases, contact Adform Support (technical@adform.com).

Error Response

A typical error response has the following structure:

Component

Description

Status code

Indicates the type of error. See the full list of possible error status codes and their descriptions in the section List of Error Status Codes below.

Headers

Metadata about the response, such as Content-Type or Request-ID.

Body

  • reason: A brief description of the error.

  • message: An explanation message associated with the reason. The message provides a more detailed summary of the error, including possible solutions.

  • params: Specific information related to the resource involved in the error. Error response doesn't always include params element.

Validation Error

Validation errors in APIs occur when submitted data fails to meet the required format, type, range, or constraints. In such cases, you'll receive a complete list of JSON parameters that have failed validation.

Validation error example

HTTP/1.1 400 Bad Request
{
   "reason":"validationFailed",
   "message":"The request is invalid.",
   "params":{
      "description":[
         {
            "message":"'Description' should not be empty.",
            "reason":"required"
         }
      ],
      "pricing":[
         {
            "message":"Pricing should be specified.",
            "reason":"required"
         }
      ],
      "currencyCode":[
         {
            "message":"'Currency Code' should not be empty.",
            "reason":"required"
         }
      ]
   }
}

Authentication and Authorization Errors

If the user doesn't have access to the required resource, or if their token is expired or invalid, the response will include a Request ID along with the Bearer tokenparameter in the header.

Authentication and authorization error examples

HTTP/1.1 401 Unauthorized

Headers:
RequestId →6b01cd4c-2bec-410f-a2b8-190cbbfd56e4
WWW-Authenticate →Bearer realm=https://id.adform.com/sts

Body:
{
    "reason": "unauthorized",
    "message": "You are not authorized to use this service"
}
HTTP/1.1 403 Forbidden

Headers:
RequestId →6b01cd4c-2bec-410f-a2b8-190cbbfd56e4
WWW-Authenticate →Bearer realm=https://id.adform.com/sts

Body:
{
"reason": "insufficientScope",
         "message": "You are not authorized to use this service",
}

Warning Messages

Some operations may generate warning messages. These messages provide additional information and alerts users to potential issues or areas for improvement, even if the main operation is successful.

Warning message example

HTTP/1.1 202 Accepted

{
    "publishStatus": "published",
    "warnings" : [
        {
            "reason": "DynamicAdWasNotPublished",
            "message": "Dynamic Ad was not published because...",
            "params": {
                "dynamicAdId": "badb94e6-6d6b-4e0f-ae41-a35fbe641638"
            }
        }
    ]
}

List of Error Status Codes

Error Code

Description

400 (Bad Request)

One or more parameters specified in the request are invalid. For example, the request might be missing a required parameter, or a parameter's value may be incorrectly specified (such as having the wrong data type or being out of range).

401 (Unauthorized)

Authentication is required to perform the action. To continue, the user must request a new access token.

403 (Forbidden)

The user isn’t authorized to access the specified resource or perform the operation. Alternatively, 403 status indicates that permission to access the resource is denied.

404 (Not Found)

The resource wasn't found. A 404 status code may also occur after an unsuccessful DELETE request if the resource has already been removed or if the query string parameters are invalid.

405 (Method Not Allowed)

The requested method (GET, POST, PUT, or DELETE) isn’t supported by the specified resource.

413 (Request Too Large)

The request exceeds the server's capacity to process.

415 (Request Unparsable)

The request is incorrectly formatted. This typically occurs when the POST body isn't specified correctly.

500 (Internal Server Error)

The server encountered an unexpected internal issue that prevented it from fulfilling the request.

501 (Method or Service Isn't Implemented Yet)

The server either doesn't recognize the request method or the method isn't supported for the targeted resource.

503 (Service Unavailable)

The server is temporarily unable to handle the request, often due to overload or maintenance.

Was this article helpful?

/
How we can make it better?

Thank you for your feedback!