Errors and status codes

Every API v3 call answers with an HTTP status code and a JSON body. Check the status code first: 2xx means the call succeeded, anything else means it failed, and the body says why.

Status codes

Code	When
`200`	The call succeeded. Write calls (add, edit, delete) return `status: true`, a `message`, the record’s `id` and its `data`.
`400`	Most errors: invalid or missing fields (“… has NOT been saved.”), the wrong HTTP method (“POST Request is required.”), a missing permission (“Permission denied. Access to “import” section is denied.”), and records that don’t exist or aren’t yours (“Import with id:5 does not exist.”, “AdSource with id:12 is not accessible.”).
`401`	No API token, or an invalid one. See API credentials.
`404`	The endpoint doesn’t exist.
`429`	Too many requests (“Max request rate limit exceeded.”).
`500`	An internal error (“An Internal Error Has Occurred.”).

Permission errors and “doesn’t exist” or “not accessible” errors return 400, not 403 or 404. Use the message to tell them apart.

Error responses

API errors (400, 429) return this envelope:

{
  "code": 400,
  "url": "/apiv3/import/edit/5.json",
  "exception": "ApiException",
  "message": "Import with id:5 does not exist."
}

When a save fails, the same envelope also carries the save result and the validation message for each field:

{
  "code": 400,
  "url": "/apiv3/import/add.json",
  "exception": "ApiException",
  "status": false,
  "message": "Import has NOT been saved.",
  "errors": {
    "validation": {
      "feed": ["Feed url invalid."]
    }
  },
  "data": []
}

Authentication errors (401) come from the token check in front of the API. They use the OAuth format and include a WWW-Authenticate: Bearer header:

{"error":"invalid_request","error_description":"The access token was not found."}
{"error":"invalid_grant","error_description":"The access token provided is invalid."}

These responses are sent with Content-Type: text/html, so parse the body as JSON whatever the header says.

An unknown endpoint (404) and an internal error (500) return a short body with name, message and url:

{"name":"Not Found","message":"Not Found","url":"/apiv3/video/nosuchaction.json"}

Handling errors

Check the HTTP status, not only the status field. A failed save is a 400, not a 200 with status: false.
400 and 401: don’t retry. Fix the request or the token first.
429: wait, then retry with an increasing delay.
500: retry later. If it keeps happening, contact support@target-video.com and include the url from the response.